Come includere documentazione di implementazione e utilizzo in un unico file

Question

Come includere documentazione di implementazione e utilizzo in un unico file

#1 da (1 voti)

0

Ci sono due tipi di documentazione.

Un tipo, la Documentazione di implementazione , contiene informazioni sull'implementazione specifica di un costrutto (ad esempio Classe, Metodo, ecc.). È mirato al futuro me, manutentore, debugger e così via.

E c'è Documentazione sull'utilizzo , contenente informazioni su come utilizzare un'API fornita. Non contiene informazioni sull'implementazione specifica e si rivolge agli utenti dell'api.

Come posso includerli entrambi in un file? (Oppure li includo entrambi in un file? E se no, che tipo appartiene al file sorgente?)

Esistono tecniche speciali, usando java-doc e / o best practice?

documentation javadocs

posta Angelo.Hannes 11.10.2013 - 15:07

fonte

1 risposta

Leggi altre domande sui tag documentation javadocs

Licenza ExtJs per applicazione gratuita Scegliere quale istanza dell'applicazione eseguirà gli aggiornamenti quando si ha a che fare con più workstation senza server coinvolti?

score 1 · Answer 1

Entrambi possono essere collegati ai file sorgente.

La Documentazione di implementazione è legata al codice, riflette le decisioni di sviluppo e va all'interno del file sorgente insieme al codice a cui è correlato.

La Documentazione sull'utilizzo in Java può essere fornita in formato javadoc, da cui è possibile estrarre la documentazione dell'API (ad esempio file HTML). È idealmente neutrale rispetto all'implementazione ma è ancora legato al codice in modo che possa essere esaminato durante l'utilizzo delle classi API quando si sviluppa utilizzando un IDE e si passa il mouse sulla classe / metodo.

/** <b>Usage Documentation</b> in javadoc format providing class description and usage. */
public class PublicClass {

    /** <b>Usage Documentation</b> in javadoc format providing method description and usage.
      * @param aParameter parameter description.
      * @return either the operation succeeded or not.
      * @throws SomeException if an exception occurred.
      */
    public boolean publicMethodThatBelongsToTheAPI(int aParameter) throws SomeException {

        /* Implementation Documentation (non-javadoc) */
        doSomething();

        (...)
    }

    private void doSomething() {
        // More implementation documentation
        (...)
    }
}