algo importante tambien va a depende (tal vez) del lenguaje, por ejemplo en c# puedes documentar tu código y medianta el VS Net te genera un XML para despues con otro programa generar los archivos .chm y te ahorras crear el manual porque al mismo tiempo que vas creando tus métodos, clases, interfaces, etc, vas documentando, un ejemplo de como yo documento es de la siguiente forma (para el caso de componentes)
Cita: /// <summary>
/// Personalize a specific control from database to get settings by module
/// </summary>
/// <param name="moduleID">Module ID to identify current control</param>
/// <returns>A Hashtable</returns>
public static Hashtable mGetModuleSettings(int pnuModuleID) {
Hashtable settings = cBLLSiteSettings.mGetSettings(pnuModuleID);
return settings;
}
ahora que si vas a documentar algun aplicacion compartida lo podrías dejar de la siguiente forma:
Cita: /// <summary>
/// Objective: Personalize a specific control from database to get settings by module
/// Author: Eduardo Sánchez Almazán
/// Date Created: 07-2006
/// Company S.A
/// </summary>
/// <param name="moduleID">Module ID to identify current control</param>
/// <returns>A Hashtable</returns>
public static Hashtable mGetModuleSettings(int pnuModuleID) {
Hashtable settings = cBLLSiteSettings.mGetSettings(pnuModuleID);
return settings;
}
como te darás cuenta la documentacion puede variar si es orientado a la creacion de algun componente, a una aplicacion donde van a intervenir varios, etc, no hay una regla donde diga que debe ir de cierto modo solo hay recomendaciones y uno establece sus propios estándares
Salu2