Page Comparison

For the sake of readability and structure we agreed in the “Community of Practice” on consistent rules for our API description: We should document our entire API mandatorily and the internal classes optionally when we consider them important. API classes are inside a package api, internal classes inside internal.

...

1. Class Description

   1. The first sentence should start with the name of the class.

   2. The first sentence should be a summary sentence, containing a concise description of the API item. It should rather describe the role of the class than its certain behavior.

      Example: (TaskService)

      1. “The TaskService creates, deletes and transfers Tasks.”

      2. “The TaskService manages all operations on Tasks.”

2. Enum Description

   1. The first sentence should be a summary sentence starting with the name of the class.

3. Method Description

   1. The first sentence should describe the intended purpose of the method precisely.

      1. starts with verb in 3. Person (uppercase)

      2. ends with dot

      3. afterwards new paragraph
         Example:

      Code Block
      /** * Transfers the specified Task to another Workbasket. <p>

   2. The inner logic of the method should be described so far that the user knows, which side effects are involved when calling a method. It should describe how the states of the objects are affected by the method. It should not describe every internal detail about the way the method proceeds.      

      Example:

      Code Block
      /** * {@linkplain Task#isTransferred() isTransferred} is set and {@linkplain Task#isRead() isRead} is reset. The {@linkplain Task#getState() state} is set * to {@linkplain TaskState#READY} and the {@linkplain Task#getOwner() owner} to NULL.

   3. Getter should be described using “Returns …” instead of “Gets …”.    

      Example:

      Code Block
      /** * Returns the id of the parent Classification. * * @return parentId */

   4. Getter that have return value of type boolean should be described using following phrasing:
      i. Returns true if ... or
      ii. Returns whether …

4. Parameter Description(@param)

   1. Used for every Parameter passed to a method.

      Example:

      Code Block
      /** * @param taskId the {@linkplain Task#getId() id} of the {@linkplain Task} which should be transferred

      1. only a phrase

      2. begins with “the” (lowercase) or with a verb

         1. The noun followed by “the” should not reference the parameter name.

      3. ends without dot

      4. when more information / phrases necessary, divided by a semicolon

   2. If not setter method: Should add description beyond the API name of the parameter.

      Example: (workbasketKey)

      1. “the key of the Workbasket”

      2. “the key of the Workbasket the Task should be transferred to”

5. Return Value Description (@return)

   1. Used for every non-void method.

      Example:

      Code Block
      /** * @return the updated {@linkplain Task}

      1. only a phrase

      2. begins with “the” / “a” (lowercase)

      3. ends without dot

      4. when more information / phrases necessary, divided by a semicolon

      5. proposal: the return value of a getter consists only of the parameter name, without “the” or “a” in the beginning

6. Exception Description (@throws)

   1. Used for every Exception thrown by a method.

      1. only a phrase

      2. begins with if (lowercase)

      3. ends without dot

      4. when more information / phrases necessary, divided by a semicolon

   2. Should add description beyond the Exception name.

      Example: (NotAuthorizedException)

      1. “if the user is not authorized”

      2. “if the user has no transfer permission for the source Workbasket”

7. Overloaded & setter Methods (@see)

   1. Used for overloaded methods when…

      1. …they are chained

         Example:

         Code Block
         default Task transfer(String taskId, String workbasketKey, String domain) { return transfer(taskId, workbasketKey, domain, true); }

      2. …the logic of both is identical

         Example:

         transfer by Key and Domain vs. transfer by Id

   2. Used also for setter-methods and referring to the corresponding getter-method.

   3. Explain the method in one phrase as done with all other methods, but leave out further information. Just refer with @see to the called / almost identical method which should describe all necessary information as specified. If the parameters differ, only explain the different ones.

   4. Use the annotation @SuppressWarnings("checkstyle:JavadocMethod") to circumvent Checkstyle.

      Example:

      Code Block
      /** * Transfers a {@linkplain Task} to another {@linkplain Workbasket} while always * setting the transfer flag. * * @see #transfer(String, String, String, boolean) */ @SuppressWarnings("checkstyle:JavadocMethod")

8. Linking Classes (@linkplain)

   1. We should link…

      1. …all our mentioned public API TASKANA classes.

      2. …fields by their corresponding getter-method.

      3. …public methods (without additional text).

      Example:

      Code Block
      /** * Transfers the {@linkplain Task} to another {@linkplain Workbasket}. <p> * The transfer sets the {@linkplain Task#isTransferred() transfer} flag.

   2. We should only link components of our public API. We should not link…

      1. ...internal classes, e. g. TaskImpl

      2. ...classes from external libraries, e. g. List, Map or Instant

      3. ...the class or its attributes itself, e. g. not link the id of the Task in Task

   3. When linking a class while referring to multiple Instances we include the s within the link.
      Example:
      

      Code Block
      /** * There can be a huge amount of {@linkplain Task Tasks} the SPI has to handle.

9. Linking (Entity) Attributes

   1. When referencing an attribute of a class, we link it to it’s getter-method. The display text of the linked value should match our Entity naming guide, found in Backend Coding Guidelines.

      Example:

      Code Block
      /** * Changes the {@linkplain Task#getClassificationSummary() classificationSummary} of the * specified {@linplain Task}. * This is a link to a {@linkplain ClassificationSummary#getServiceLevel() serviceLevel}

10. Linking Enum values

    1. When referencing an enum value, we link to the value only. No text should be added to the link.

       Example:

       Code Block
       /** * @throws NotAuthorizedException if the current user has no {@linkplain * WorkbasketPermission#READ} for the {@linkplain Workbasket} the {@linkplain Task} is in

11. Spelling and phrasing

    1. When referencing attributes from their class, use either the description of their content, or their original names.

       Example:

       Code Block
       /** * Returns the externalId of the Task. * * @return externalId */

    2. 'NULL' is written in uppercase

    3. 'id' is written in lowercase, except in the beginning of the sentence

    4. Instant, Map, List and other external classes and data structures are capitalized

    5. Everything else starts with lowercase or uppercase according to English grammar

    6. Use contractions like wasn’t, isn’t and doesn’t (instead of the full versions)

...