Adding javadocs to methods in fabric-carpet

[Ghoulboy78]

A mirror of #831 , I realised that it worked better as a discussion.

I believe that while a monumental task, this is useful for contributors trying to understand what the code does. For example, look at like ShapeDispatcher.java, where the code is so complicated that it takes quite a while to even begin to understand what's going on. This is also the case in like Tokenizer.java and Expression.java for people who wanna understand how scarpet works, or for eg in CarpetSettings for people who wanna understand how carpet rules work.

On the other hand, adding javadocs may bloat the files unnecessarily perhaps? And if we decide to add them, we ought to have someplace to check who has added what. Perhaps the javadocs could be added to a different branch or something, so the main one is unaffected, tho that would be tedious to update that branch as well all the time.

Ok, now after consultation with gnembon, there is a new plan:

The plan

Similarly to #837, we will have a list of the diffferent parts of the code. In this case, it's one checkbox for each concept and group of files, as in the code functions from one file can be used everywhere, so below are listed the different topics/areas

• All the different values (everything that is an instance of Value.java)
• ValueConversions.java
• Scarpet Events system (including entity events and entity load handler)
• App loading via script command
• App unloading via script command
• All the carpet rules, including their relevant mixins, interfaces, helpers and utils
• Messenger.java

Carpet Commands

• CounterCommand.java (Ghoulboy in Adding Javadocs to CounterCommand.java and relevant files #838)
• DistanceCommand.java
• DrawComand.jjava
• InfoCommand.java
• LogCommand.java
• MobAICommand.java
• PerimeterInfoCommand.java
• PlayerCommand.java
• ProfileCommand.java
• ScriptCommand
• TickCommand.java

Parsing of Scarpet

• Tokenizer.java
• Expression.java
• CarpetExpression.java
• Fluff.java, Context.java
• CarpetContext.java
• ScriptHost.java
• CarpetScriptHost.java
• CarpetScriptServer.java

All the Scarpet functions:
API:

• Auxiliary.java
• BlockIterators.java
• Entities.java
• Inventories.java
• Monistoring.java
• Scoreboards.java
• Threading.java
• WorldAccess.java

Language:

• Arithmetic.java
• ControlFlow.java
• DataStructures.java
• Functions.java
• Loops.java
• Operators.java
• Sys.java
• Threading.java

Please refrain from adding javadocs to unimportant private fields/variables, not to getters and setters. Also don't add javadocs to files in carpet.fakes, as yarn ma have beter and more up-to-date javadocs for them. Also make sure to add returns - and throws- to the javadocs where appropriate and where necessary.

See my first comment below to see how to choose an option from above. Please list all the relevant files which would need to be updated, and if only part of a file has relevant functions to your option, then only update those functions. Also please keep discussions in the space provided by the PR.
Also try to have only 1 javadoc update PR open at a time (This is as much an instruction as a note to self...)

[Ghoulboy78]

Example:
I would like to update the javadocs for CounterCommand.java. It is in a branch https://github.com/Ghoulboy78/fabric-carpet/tree/javadoc-update-CounterCommand.java and PR #838

[altrisi]

Let me add a few ideas, which is what I've seen in most javadoc conventions out there that have worked quite nicely, and a few own things.

• Always javadoc method parameters when javadocing, even if it seems obvious, can help substantially.
• Specify return and things. A method doc saying "The total of something" may be ambiguous. Does it return that total? Sum the total and then returns the total? One of its parameters must be such total?
  Also "Returns whether a variable is met". Does it return true when the variable is met, or false? (imagine something that sounds negative by itself)
• Don't javadoc private variables, and if doing so, only the ones that aren't specified in a constructor or something. IMO that is actual bloat.
• Don't add javadoc to simple getters and setters in the fakes package, since it's too obvious what they do and yarn may actually have more up to date documentation in their field's name
• Don't actually javadoc everything. Javadoc only everything public (to extensions). Javadoc kind-of makes a contract that the method will have a specific behaviour and signature that will be preserved, that may not be really desired since then extensions can consider them Public API, and then an update may drop and break it unless such Public API rule is followed, which makes it annoying and bad to change things while keeping old behaviours.

If javadocing eveything, we should actually make a convention so docs are at least consistent.

[Ghoulboy78]

hmm, that seems fair