adventure
adventure copied to clipboard
KyoriPowered
Improve Javadocs for key API interfaces and methods
One pain point in any project is documentation. As developers, we hate writing it, but ultimately, we love reading it. Adventure is unfortunately somewhat light on some of the javadocs and could do with some love.
Javadocs and comments should tell you what the code cannot. Component is actually a really good example of both a good use and bad use of Javadocs.
https://github.com/KyoriPowered/adventure/blob/3af760f73830902f1a546f905ef1565814d9bc50/api/src/main/java/net/kyori/adventure/text/Component.java#L49-L62
The bad: I could have told you that Component was a component... but what is a component in itself? If you're coming to Adventure to work with text, then it's something you should probably already know, however from the context of the Sponge platform, some people will see that and not be so sure about the fact that text is made up of components. This doc could do with a small explanation about how it is the basic class for text display in Minecraft - a Component is what is ultimately displayed by the client. You could also link it to the Kyori adventure docs too.
The good: The fact it links to important subclasses. I can see some of the types of Component we can use. I wasn't aware of some of these uses - brilliant! Let's take a look a TranslatableComponent, I wasn't aware Adventure has that...
https://github.com/KyoriPowered/adventure/blob/3af760f73830902f1a546f905ef1565814d9bc50/api/src/main/java/net/kyori/adventure/text/TranslatableComponent.java#L29-L50
...oh, I have no idea where the translations go, what the key is. Can I create my own (I think I can)? Where is the registry of valid translations - can I get that via Adventure or is that a platform thing?
This is the sort of thing that I feel is missing from the Javadocs - there are methods that just need more explanation as to what is going on, particularly when a Key is involved, signposts to how it all comes together would be good.
It's very important to note that not all the methods need much in the way of docs. Some of the methods are self documenting, such as TextComponent.Builder#content(String). Setting the content of a builder should be obvious, I hope! Same with a colour, a style (aside: I didn't realise that events were considered part of the style today!) - things that are self documenting.
This issue is wide ranging and it's not something that I've opened lightly. If time permits, I will volunteer to join in the effort and try to improve the documentation as I come across things and try to use it - after all, I want such a project to succeed.
The fact it links to important subclasses.
But doesn't javadoc tool automatically show directly known subclasses for classes and implementing classes for interfaces? These @see links are just extra futile work.
But doesn't javadoc tool automatically show directly known subclasses for classes and implementing classes for interfaces?
Not for those that read the JDs directly from the code or in their IDE.
Is there anything that really needs improving currently, or is the javadocs at a good enough point to resolve this issue for now?
