So come documentare una funzione:
/**
* Prints a greet message to the web page
*/
function greet() {
echo "Hi!";
}
O descrivi l'uso di una variabile:
/**
* @type string $name The user's name
*/
$name = "Bas";
Ma non so come documentare un'interfaccia. Richiede le classi che implementano l'interfaccia per avere le funzioni che si trovano all'interno dell'interfaccia, e il gioco è fatto.
Domanda
Come documenta un'interfaccia?
Descrivi lo scopo e l'utilizzo dell'interfaccia e lo scopo e l'uso delle funzioni nell'interfaccia.
Ecco un esempio di .NET Framework (semplificato per brevità). Nota la "dichiarazione di intenti" e le note specifiche su jitting e hack interni, cose che non sarebbero affatto ovvie solo guardando il codice dell'interfaccia:
// Implement this interface if you need to support foreach semantics.
// Note that T[] : IList<t>, and we want to ensure that if you use
// IList<yourvaluetype>, we ensure a YourValueType[] can be used
// without jitting. Hence the TypeDependencyAttribute on SZArrayHelper.
// This is a special hack internally though - see VM\compile.cpp.
// The same attribute is on IList<t> and ICollection<t>.
public interface IEnumerable<out t=""> : IEnumerable
{
// Returns an IEnumerator for this enumerable Object. The enumerator provides
// a simple way to access all the contents of a collection.
/// <include file="doc\IEnumerable.uex" path="docs/doc[@for="IEnumerable.GetEnumerator"]/*">
new IEnumerator<t> GetEnumerator();
}
Vale la pena notare che parte della documentazione che descrivi nella tua domanda è inutile o ridondante. Non documentare cose ovvie. Invece, rendi le cose ovvie in modo che tu non debba documentarle.
La documentazione è solo un'altra cosa che devi mantenere e mantenere sincronizzata, quindi documenta per i giusti motivi. Consenti al log del codice di parlare da solo, ma documenta le relazioni tra metodi e classi, spiega le cose oscure e, in generale, sii utile senza ripetere te stesso.
Leggi altre domande sui tag interfaces php documentation