Java-documentatie – @return en @param

Ik vraag me af hoe ik code kan documenteren met @return en @param …? Ik vermoed dat ik zoiets zou doen als

@return(whatever the method is returning)
@param(parameters that the method is taking in)

Moet ik achteraf meer beschrijvingen plaatsen? Is er ook zoiets als teveel documentatie?

Antwoord 1, autoriteit 100%

De Javadoc-stijlgidslegt de bedoelde gebruik van deze tags. @parambeschrijft een parameter en @returnbeschrijft de retourwaarde. (Er zijn verschillende andere handige tags.)

Onthoud dat Javadoc documentatie genereert uit uw code, niet alleenuit uw opmerkingen. De handtekening van de methode zal in de uitvoer verschijnen — daarom vertel de lezers geen dingen die ze al weten. Het doel van uw documentatie is om de aanvullende semantiek te leveren die niet in de handtekening wordt uitgedrukt. Is die numerieke parameter beperkt tot een bepaald waardenbereik? Zijn er speciale retourwaarden (zoals null)? Documenteer het contract.

Je vraagt of er zoiets bestaat als teveel documentatie. Ja dat is er. API-referentiedocumentatie is het nuttigst wanneer het de lezers alles vertelt en alleen wat ze moeten weten om de interface correct te gebruiken. Dus documenteer het contract volledig, maar zeg niets over hoe uw code deze interface implementeert. Link naar andere elementen van de API (zoals andere klassen of interfaces) als ze rechtstreeks betrekking hebben op het deel dat u documenteert (bijvoorbeeld als iemand SomeFactorymoet gebruiken om een exemplaar van SomeThing, de klas die je documenteert).

Dit is niet te zeggen dat je nooit langer iets meer dan een paar zinnen zou moeten schrijven; Soms is een interface complex en vereist meer uitleg. Overweeg of die verklaring behoort in een pakketoverzicht, de documentatie op het hoogste niveau van een klasse of interface of een specifiek lid. Als u merkt dat u een uitleg op verschillende plaatsen snijdt en plakt, is dat mogelijk een teken dat u deze op een hoger niveau moet aanpakken.

Antwoord 2, Autoriteit 22%

Die dingen zijn Javadoc-tags. Volledige referentie van het gebruik van deze u kunt hier vinden: http: / /www.oracle.com/technetwork/java/javase/documentation/index-137868.html

Maar basisvoorbeeld voor die twee die u hierboven hebt genoemd, ziet er als volgt uit:

/**
 * Adds two values.
 *
 * @param operand1 - first numeric value for the ADD operation
 * @param operand2 -  second numeric value for same purposes
 * @return sum of two operands
 */
 public int add(int operand1, int operand2) {...}

Javadocs worden altijd gebruikt vóór de methode of variabele of klasse / interface

Antwoord 3, Autoriteit 4%

Waarom niet beginnen met het opzoeken van wat Javadocs zijn?

http://en.wikipedia.org/wiki/javadoc

Een voorbeeld van hoe ze worden gebruikt, is als volgt.

/**
 * Gets the id of the player.
 *
 * @param someParam you'd put a description of the parameter here.
 * @return the id of the object.
 */
public int getId(int someParam) {
    return this.id;
}

Antwoord 4, Autoriteit 4%

Dit is Javadoc waar je het over hebt:

/**
 * Subject line
 *
 * <p>Description of the method with optional {@code code} and {@link Object links to Javadoc}
 * </p>
 *
 * <pre>
 *    raw input
 * </pre>
 *
 * @param foo first arg
 * @return a bar
 * @throws SomeException if bar goes wrong
 * @see someOtherMethod()
 * @since 2.2.2
 * @author me
 */
int doSomething(final int foo)
    throws SomeException
{
    // etc
}

De javadoc-tool (en doelen die deze tool gebruiken in verschillende buildsystemen zoals gradle en maven) zullen daaruit HTML-bestanden genereren.

Moet ik achteraf meer beschrijvingen plaatsen?

Vroeger, in feite, als een conventie. En alleen als je het nodig acht.

Is er ook zoiets als teveel documentatie?

Ja.