More Documentation

[lucasstarsz]

Now that the wiki has been added, we need to have documentation that matches its clarity.

[lucasstarsz]

We're also going to want to set a standard for how docs should be written for each javadoc segment. The format will be present below.

[lucasstarsz]

Slope-ECS Javadoc Format

This is where all documentation of the parts of Slope-ECS will have their documentation style defined.

Style of Javadocs

• Any Javadoc segment that extends past a single line (essentially all elements except variables) should have asterisks (stars that look like this: *) along the side, one space in front of the forward-slash (slash that looks like this: /) that starts the Javadoc segment.
• Newlines between sections (covered in more detail later) should not contain singular <p> elements, as this causes compile errors in the Java 15 Javadoc. This is not the default in IntelliJ -- change it by going to File → Settings → Editor → Code Style → Java → JavaDoc. Under Other, remove the checkmark for Generate "<p>" on empty lines. Then, add the checkmark to Keep empty lines.
• Section names should be enclosed in Heading tags.
  • For classes, use <h2>Section Name</h2>
  • For all other elements, use <h4>Section Name</h4>
• Javadocs (and your code, for that matter) should hard wrap at 120 characters.
• The result should look like this:

  /**
  * one-liner.
  *
  * <h2>Section Name</h2>
  * Lorem Ipsum, which I'm too lazy to grab from the internet and bother formatting. This is a sentence that will be
  * hard-wrapped at 120 characters.
  *
  * <h2>Another Section Name</h2>
  * More lorem ipsum, perhaps.
  */
  public class Example {}

Javadoc Rules

General Javadocs

One-Line Description

A single sentence describing the method, class (or variant), or variable's purpose in the code.

• This rule applies regardless of the element's visibility.

General Javadoc, excluding variables

About Section

The section immediately declared after the one-liner.

• this section should describe, in detail (in several paragraphs if you have to), the element's purpose and how it works.
• this section can also contain references to sources outside the source documentation if a better, more clarifying explanation can be found. This does not mean the element should not be described in the documentation. The external link is meant to be an auxiliary source of information on an element's purpose -- or even the bigger picture containing that element.

Author

Declared with the @author Javadoc tag, the author or authors of an element should be specified. While you are not required, it is strongly recommended you put your real name instead of your display name. (For example, I put Andrew Dey instead of lucasstarsz.) I understand that user anonymity is always a concern, but this is an open-source library -- by putting your name on something, you should be able to take credit for it in the business world.

Origin Version

Declared with the @since Javadoc tag, the original version in which an element was implemented should be specified.

• just a reminder that methods exposed to the outside developers should not be added in patch version increments
  • Correct: adding a publicly available method when going from 0.1 to 0.2.
  • Incorrect: adding a publicly available method when going from 0.1.1 to 0.1.2.
  • For cases where you are adding an internal element during a patch version increment, explain its purpose in being added as plainly as possible. It's a patch -- we should know what it does, why it does what it does, and what it was fixing (which doesn't mean you should paste your entire commit message in there!).

Current Version (ONLY IF MODIFIED SINCE ORIGINAL)

Declared with the @version Javadoc tag, the current version should be specified only if the element was modified since the original version. The current version does not need to be specified for every release increment if the element did not change during that increment.

• IMPORTANT: if an element was modified such that it needs to have its @version tag updated, then the reasoning behind the update should be specified in the about section of its documentation. The reasoning should come straight from the git commit message from when that method update happened. If the reasoning is more than a few sentences, then a brief statement about the change complemented by a link to the commit where the change was implemented will suffice.

Methods

Example Usages

Coming after the element's about section, this section is to provide a usable, understandable sample code to demonstrate what an element does and its effect on other things outside of its state.

• The example code should try and keep initialization segments to a minimum, and separate (by a new line) from the code most relevant to the reader.
• The example code should also be wrapped in a {@code } Javadoc tag, which is then wrapped in a <pre> HTML tag. The result is shown in the example.

Getter/Setter methods

• Unless the getter/setter method produces a side effect (as in, if the method does anything other than returning the appropriate/expected value based on the method name), these should make use of the inline {@return } tag. This Java 16 feature allows for non-verbose documentation of getter/setter methods and will be a staple in the documentation style.
• If possible, usage of the inline {@return } tag for getter/setter methods should be maintained in a single line of Javadoc.

Example Javadoc

This class would be part of a mock library currently in version 0.2.4:

/**
 * An example class depicting the way documentation should be written in Slope-ECS.
 *
 * <h2>About</h2>
 * Rather than expect people to read my mind and understand exactly what I want in the Slope-ECS Javadoc, I chose to 
 * write this format guide instead. Hopefully, it will give you all an understanding of what I expect for the Javadocs 
 * in this library.
 * 
 * @author Andrew Dey
 * @since 0.1
 */
public class DocumentationExample {
    /** An integer to aid me in giving an example Javadoc. */
    private int foo;

    /**
     * The default constructor for the {@code DocumentationExample} class.
     *
     * <h4>About</h4>
     * Oh yes, I'm sure you'd get tired of writing the section name every time. Well, there isn't really a way to avoid
     * needing to write in this format, unless at some point we make a custom doclet which adds these things as
     * custom annotations. That would be cool if we could come up with that, just throwing it out there.
     *
     * This constructor only serves to initialize the internal values of the class.
     * 
     * @author Andrew Dey
     * @since 0.1
     */
    public DocumentationExample() {
        foo = 1;
    }

    /**
     * Prints the value of {@link #foo}, then adds the parameter to it.
     *
     * <h4>About</h4>
     * This method purely serves the purpose of printing and modifying the {@link #foo} variable. The original value
     * gets printed out first; {@code foo} then gets the {@code fooModifier} parameter added to it.
     *
     * <h4>Example Usages</h4>
     * <pre>{@code
     * DocumentationExample example = new DocumentationExample();
     * System.out.println("Original value of foo: " + example.getFoo());
     * example.printFoo(5);
     * System.out.println("Foo, after it was modified: " + example.getFoo());
     * 
     * // This code will print the following:
     * // Original value of foo: 1
     * // 1
     * // Foo, after it was modified: 6
     * }</pre>
     * 
     * @param fooModifier The value to add to {@link #foo}.
     * 
     * @author Andrew Dey
     * @since 0.2
     */
    public void printFoo(int fooModifier) {
        System.out.println(foo);
        foo += fooModifier;
    }

    /** {@return the value of {@link #foo}} */
    public int getFoo() {
        return foo;
    }
}

If any questions persist beyond what this guide covers, or if you think something should be added or specified, please open an issue and let your voice be heard.

[lucasstarsz]

As suggested by an anonymous person, we should consider allowing display names in the @author section instead of just business names. Until further notice, that will be allowed so long as the name is not inappropriate.

[lucasstarsz]

Due to HTML compile issues, we will no longer have empty lines use the <p> tag.

[lucasstarsz]

Thanks to more HTML compile errors, and some interesting CSS, class headings will now use <h2> for sections; all other elements will use <h4>.

[lucasstarsz]

All the formatting errors have been resolved. Awaiting release.

[lucasstarsz]

In the Java 16 specification, the new recommended way to avoid duplication for getters/setters is to use the inline {@return } tag, which avoids repeating yourself. For the foreseeable future, this will be the way getter/setter methods are documented.