adventure icon indicating copy to clipboard operation
adventure copied to clipboard

Improve documentation and discoverabilty of LinearComponents.linear()

Open dualspiral opened this issue 4 years ago • 1 comments

This issue is taken from https://github.com/SpongePowered/SpongeAPI/pull/2275#issuecomment-739912355

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:

https://github.com/KyoriPowered/adventure/blob/3af760f73830902f1a546f905ef1565814d9bc50/api/src/main/java/net/kyori/adventure/text/LinearComponents.java#L39-L45

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.

dualspiral avatar Dec 07 '20 17:12 dualspiral

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

astei avatar Dec 14 '20 13:12 astei