Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
dualspiral opened this issue Dec 7, 2020 · 1 comment · May be fixed by #258
Open

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

dualspiral opened this issue Dec 7, 2020 · 1 comment · May be fixed by #258
Labels
area: api status: needs discussion An issue or PR that requires design decisions or further consensus building before it can be merged type: question

Comments

@dualspiral
Copy link

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.

@astei
Copy link
Contributor

astei commented Dec 14, 2020

I talked about this on Discord a bit. I think this would be a lot better if we called it Component.compose(ComponentBuilderApplicable...) instead.

@zml2008 zml2008 added the status: needs discussion An issue or PR that requires design decisions or further consensus building before it can be merged label Nov 7, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area: api status: needs discussion An issue or PR that requires design decisions or further consensus building before it can be merged type: question
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants