Documentació

[miqueldedo]

Bones Miquel, Sobre la documentació, tinc un parell de dubtes:

• Hem de posar sempre el valor @param a les funcions indicant què volen dir els paràmetres?
• En els constructors sempre hem d'indicar els paràmetres?
• Si especifiquem en el @post o en el @brief el valor que retorna la funció, cal especificar el valor @return?

[miquelbofill]

Si la @pre i @post són prou detallades, no cal @param. De totes maneres, es pot posar si es desitja.

El @return només es sol posar si no hi ha cap més post-condició. Seria un cas particular de post-condició.

El @brief sí que l'heu de posar, com a resum.

En els constructors sempre hem d'indicar els paràmetres?

No sé a què et refereixes amb "indicar". En tot cas, per indicar quin és el resultat (post-condició) bé que t'hi hauràs de referir.

[miqueldedo]

Em refereixo a si hem d'explicar què és cada paràmetre amb @param dels que s'entren al constructor.

[miquelbofill]

Sí, pots fer-ho amb @param. Però també amb @pre/@post. Potser el més assenyat seria discutir-ho amb algun exemple concret.

[miqueldedo]

Per exemple, al següent constructor de peça (extret del mateix codi):

/// @brief Default constructor with symbol
Piece(PieceType type, String symbol, boolean moved, PieceColor color) {
    this.id = idGenerator;
    this.type = type;
    this.moved = moved;
    this.color = color;

    /// Since type symbol will ALWAYS be uppercase, we only nee to change it
    /// if the piece color is black.
    this.symbol = color.toString().equals("NEGRES") 
        ? type.ptSymbol().toLowerCase()
        : type.ptSymbol();

    idGenerator++;
}

Hauria d'identificr cada paràmetre el que és?

[miquelbofill]

Sí, en aquest cas hi pots posar els mateixos comentaris que tens en els atributs privats. Pensa que el constructor és el que apareixerà a la documentació pública, i no els atributs.

Recorda que també cal donar una descripció general de la classe (idea intuïtiva de què representa a nivell abstracte).