Skip to content

Improve documentation and discoverabilty of LinearComponents.linear() #225

Open
@dualspiral

Description

@dualspiral

This issue is taken from SpongePowered/SpongeAPI#2275 (comment)

LinearComponents.linear() is clearly designed to ease the burden of creating a tree like structure, but is hindered by the fact that it's not obvious what it is, why it's there, how it works. The documentation says this:

/**
* Creates a component "linearly".
*
* @param applicables the things used to make the component
* @return a component
* @since 4.0.0
*/

which tells me nothing about it and devalues the existence of the function. Until recently, I was under the impression that it was mostly to be used to effectively join multiple components together - however, based on recent conversations, it actually aspires that it can be used for more than that - like including colours and styles. I have no idea how that works - does it work like Sponge API 7's Text.of() when it comes to colours and styles?

It's also not a particularly descriptive name: to most people it's not going to be obvious that "linear" components means the same as this Text.of(...) - people I know only know of it because I told them about it (and even then, I should just use a join method)! It might be better on the Component interface - but it certainly needs fleshing out in terms of documentation and what it can do.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: apistatus: needs discussionAn issue or PR that requires design decisions or further consensus building before it can be mergedtype: question

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions