Skip to content

Improve documentation and discoverabilty of LinearComponents.linear()

Open

Description

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

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 mergedAn 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