Documentation

[darbyjack]

Start working on documentation that will be useful for the end-user to understand as they read the code.

[Andre601]

I could help implementing docs.
I just need to know what the format would be in this case.

[PiggyPiglet]

We're planning on using a similar style to that of which you linked the other day in Help Chat. It may not be identical though, so I'd recommend just looking at the current documentation we have. PlaceholderExpansion would be a good place to start.

[Andre601]

Which classes and what methods would require documentation?

[PiggyPiglet]

Ideally everything. Most importantly for now though, the methods that the expansion developer will interact with. It's important to note however, that documentation should be written in two different ways throughout the project. If it's to be interacted with via expansion, it should be written for them. If it's for internal use, it should be written for us.

For example, and sorry glare, but I need to use your mistake as an example, originally we had this in ExpansionInfo:

/**
 * Retrieves the name from the annotation
 * @return name
 */
String name();

/**
 * Retrieves the author from the annotation
 * @return author
 */
String author();
}

The documentation on these two methods, is really bad, as it's not useful at all to the developer of the expansion, that is using this annotation. In it's current state, it's only useful to us, the internal developers, as it describes what the method literally returns, although you'd hope this could be inferred from common sense due to the naming. Instead of saying Retrieves the name from the annotation, you should be explaining what the name is, what it will be used for, and if you're feeling especially helpful, why.

[Andre601]

That honestly doesn't make it that easier as I now would need to know what classes and methods are for devs and what for internal use.
So an actual list of them could be benefitial.

Also, wouldn't it be better to have param and return values with an empty line in between for better reading in the case that a dev reads the comments in their IDE?

And finally wouldn't it be benefitial to have an interface like part of the api for the devs to keep the api separated?
That could allow only providing the methods/classes needed for the devs without giving unwanted internals. I of course are fairly new to this and therefore are not sure if this would even work.

[PiggyPiglet]

I'm not going to write a list right now, as such a list would likely become redundant after a single commit, not even necessarily related to the API, which should give you an idea of how volatile everything currently is. Generally though, if it's abstract (required to implement, not necessarily literally abstract), and explicitely labelled as part of the API, it's for the developer. If not, it's internal.

Yes.

Sort of, not quite that simple unfortunately, especially with the API design I wish to use. Although the separation of the general API and the common module is probably wise, and something that will be present in my next push.

-

I'll update the main post of this issue with an official spec soon, but as I said eariler, the project is too volatile atm to bother writing standards that will likely become redundant shortly after.

[Andre601]

Just came back to this issue and thought about what structure for docs we should use.

I personally propose this general doc structure due to it being fairly readable for IDE users that check docs directly and not the rendered HTML version (if there will ever be one that is).

/**
 * A single line with some simple text.
 * 
 * <p>A new paragraph. The p tag won't be closed.
 * <br>New lines are having a simple br tag.
 * 
 * @param name
 *        Parameter description on a new line for better readability.
 * 
 * @return Description of what is returned, even if it would repeat the same line at the start.
 * 
 * @see #someOtherMethod() String: someOtherMethod()
 */
public String someMethod();

The most noticeable thing is the @see tag which would display a See also link to another method in the format <type>: <method name> giving an idea of what the mentioned method returns.
I also consider flipping this around to be <method name>: <type> instead, but not sure which one would be better.

(Also, yes, I'm aware that PAPI3 is not yet done, but I want to get SOME discussion going here....)