Dokumentationsköpfe

[Carsten1975]

Wie gestaltet ihr eure Dokumentationen in den Programmen, Packages und Units, sowie für die Prozeduren und Funktionen?

Also ich habe mir in den letzten mehr als 30 Jahren folgende Dokumentationsköpfe zurecht gebastelt.
Vielleicht nimmt der ein oder andere Anfänger diese auch für sich als Vorlage.

Programm

Code: Alles auswählen

// *****************************************************************************
// **                                                                         **
// **  Programm: Testprogramm                                                 **
// **                                                                         **
// **  Unitname: FTestprg                                                     **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Stellt die Oberfläche vom Testprogramm zur Verfügung.                  **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Prozeduren   : FormCreate(Sender : TObject)                    **
// **                         FormClose(Sender          : TObject;            **
// **                                   Var CloseAction : TCloseAction)       **
// **                                                                         **
// **  Private Prozeduren   : ppMenue(Sender : TObject)                       **
// **                         ppMenueClick(Sender : TMenuItem)                **
// **                                                                         **
// **  Protected Prozeduren : -----                                           **
// **                                                                         **
// **  Public Prozeduren    : -----                                           **
// **                                                                         **
// **  Published Prozeduren : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Funktionen   : -----                                           **
// **                                                                         **
// **  Private Funktionen   : -----                                           **
// **                                                                         **
// **  Protected Funktionen : -----                                           **
// **                                                                         **
// **  Public Funktionen    : -----                                           **
// **                                                                         **
// **  Published Funktionen : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Globale Klassen    : FrmTestprg : TFrmTestprg                          **
// **                                                                         **
// **  Globale Konstanten : -----                                             **
// **                                                                         **
// **  Globale Variablen  : -----                                             **
// **                                                                         **
// **  Globale Records    : grTestQuery                                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Aktionen: Menuepunkte : Alle Menüpunkte werden dynamisch erstellt      **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Hinweise : keine                                                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Erstellung:                                                            **
// **                                                                         **
// **  10.00.21.1230  30.12.2021  Name des Entwicklers                        **
// **                                                                         **
// **  Aenderungen:                                                           **
// **                                                                         **
// **  10.00.21.1231  31.12.2021  Name des Entwicklers                        **
// **                 Prozedure Debug hinzugefügt                             **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// *****************************************************************************

Packages

Code: Alles auswählen

// *****************************************************************************
// **                                                                         **
// **  Package: Testpackage                                                   **
// **                                                                         **
// **  Unitname: pTest                                                        **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Erstellt dynamisch die Menues.                                         **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Prozeduren   : FormCreate(Sender : TObject)                    **
// **                         FormClose(Sender          : TObject;            **
// **                                   Var CloseAction : TCloseAction)       **
// **                                                                         **
// **  Private Prozeduren   : ppMenue(Sender : TObject)                       **
// **                         ppMenueClick(Sender : TMenuItem)                **
// **                                                                         **
// **  Protected Prozeduren : -----                                           **
// **                                                                         **
// **  Public Prozeduren    : -----                                           **
// **                                                                         **
// **  Published Prozeduren : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Funktionen   : -----                                           **
// **                                                                         **
// **  Private Funktionen   : -----                                           **
// **                                                                         **
// **  Protected Funktionen : -----                                           **
// **                                                                         **
// **  Public Funktionen    : -----                                           **
// **                                                                         **
// **  Published Funktionen : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Globale Klassen    : FrmMenue : TFrmMenue                              **
// **                                                                         **
// **  Globale Konstanten : -----                                             **
// **                                                                         **
// **  Globale Variablen  : -----                                             **
// **                                                                         **
// **  Globale Records    : grMenue                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Aktionen: Menuepunkte : Enthält alle Menüpunkte                        **
// **            Debug       : Protokolliert die einzelnen Modulschritte      **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Hinweise : keine                                                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Erstellung:                                                            **
// **                                                                         **
// **  10.00.21.1230  30.12.2021  Name des Entwicklers                        **
// **                                                                         **
// **  Aenderungen:                                                           **
// **                                                                         **
// **  10.00.21.1231  31.12.2021  Name des Entwicklers                        **
// **                 Prozedure Debug hinzugefügt                             **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// *****************************************************************************

Units

Code: Alles auswählen

// *****************************************************************************
// **                                                                         **
// **  Unit: UTest1                                                           **
// **                                                                         **
// **  enthalten in Package: ----                                             **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Stellt mathematische Berechnungen zur Verfügung                        **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Prozeduren   : FormCreate(Sender : TObject)                    **
// **                         FormClose(Sender          : TObject;            **
// **                                   Var CloseAction : TCloseAction)       **
// **                                                                         **
// **  Private Prozeduren   : -----                                           **
// **                                                                         **
// **  Protected Prozeduren : -----                                           **
// **                                                                         **
// **  Public Prozeduren    : -----                                           **
// **                                                                         **
// **  Published Prozeduren : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Klassen Funktionen   : -----                                           **
// **                                                                         **
// **  Private Funktionen   : -----                                           **
// **                                                                         **
// **  Protected Funktionen : -----                                           **
// **                                                                         **
// **  Public Funktionen    : Multiplikation(Wert1 : Integer;                 **
// **                                        Wert2: Integer) : Integer        **
// **                                                                         **
// **  Published Funktionen : -----                                           **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Globale Klassen    : gUTest1 : TTest1                                  **
// **                                                                         **
// **  Globale Konstanten : Faktor : 100                                      **
// **                                                                         **
// **  Globale Variablen  : -----                                             **
// **                                                                         **
// **  Globale Records    : -----                                             **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Aktionen: Multiplikation : Multipliziert Wert1 mit Wert2               **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Hinweise : keine                                                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                       **
// **                                                                         **
// *****************************************************************************
// **                                                                         **
// **  Erstellung:                                                            **
// **                                                                         **
// **  10.00.21.1230  30.12.2021  Name des Entwicklers                        **
// **                                                                         **
// **  Aenderungen:                                                           **
// **                                                                         **
// **  10.00.21.1231  31.12.2021  Name des Entwicklers                        **
// **                 Prozedure Debug hinzugefügt                             **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// **                                                                         **
// *****************************************************************************

Prozeduren

Code: Alles auswählen

    // *************************************************************************
    // **                                                                     **
    // **  Prozedure: FormCreate(Sender: TObject)                             **
    // **                                                                     **
    // **  enthalten in Unit     : FTestprg                                   **
    // **  enthalten im Package  : ----                                       **
    // **                                                                     **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Startet die Maske des Testprogrammes.                              **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Status: Klassenmodul [X]                                           **
    // **          Private [ ]   Protected [ ]   Public [X]   Published [ ]   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Aktionen: Initialisierung : Initialisiert alle Variablen           **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Hinweise : keine                                                   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Erstellung:                                                        **
    // **                                                                     **
    // **  10.00.21.1230  30.12.2021  Name des Entwicklers                    **
    // **                                                                     **
    // **  Aenderungen:                                                       **
    // **                                                                     **
    // **  10.00.21.1231  31.12.2021  Name des Entwicklers                    **
    // **                 Neue Variablen hinzugefügt                          **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // *************************************************************************

Funktionen

Code: Alles auswählen

    // *************************************************************************
    // **                                                                     **
    // **  Funktion: Multiplikation(Wert1 : Integer;                          **
    // **                           Wert2: Integer) : Integer                 **
    // **                                                                     **
    // **  enthalten in Unit     : UTest1                                     **
    // **  enthalten im Package  : Testpackage                                **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Multipliziert Wert1 mit Wert2.                                     **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Status: Klassenmodul [ ]                                           **
    // **          Private [ ]   Protected [ ]   Public [X]   Published [ ]   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Aktionen: siehe Beschreibung                                       **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Hinweise : keine                                                   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                   **
    // **                                                                     **
    // *************************************************************************
    // **                                                                     **
    // **  Erstellung:                                                        **
    // **                                                                     **
    // **  10.00.21.1230  30.12.2021  Name des Entwicklers                    **
    // **                                                                     **
    // **  Aenderungen:                                                       **
    // **                                                                     **
    // **  10.00.21.1231  31.12.2021  Name des Entwicklers                    **
    // **                 Prüfung auf Negativzahlen                           **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // **                                                                     **
    // *************************************************************************

Selbstverständlich gilt trotzdem weiterhin der Satz:

Ein guter Programmierer dokumentiert immer alle sich nicht selbsterklärenden Programmzeilen!


Viel Spaß beim dokumentieren.

[Winni]

Hi!

Schön wenn Menschen etwas dokumentieren. Stirbt anscheinend aus.

Aber die vielen Doppel-Slash kannst Du Dir sparen:

Code: Alles auswählen

(**********************************************

Und nun kannst Du losschreiben,
wie Du  möchtest.
***********************************************
Und noch mehr Text

***********************************************)

Winni

[Carsten1975]

Hier habe ich das Ganze mal nach WInni seinem Vorschlag gestaltet.

Programm

Code: Alles auswählen

(******************************************************************************
 **                                                                          **
 **  Programm: Testprogramm                                                  **
 **                                                                          **
 **  Unitname: FTestprg                                                      **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Stellt die Oberfläche vom Testprogramm zur Verfügung.                   **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Prozeduren   : FormCreate(Sender : TObject)                     **
 **                         FormClose(Sender          : TObject;             **
 **                                   Var CloseAction : TCloseAction)        **
 **                                                                          **
 **  Private Prozeduren   : ppMenue(Sender : TObject)                        **
 **                         ppMenueClick(Sender : TMenuItem)                 **
 **                                                                          **
 **  Protected Prozeduren : -----                                            **
 **                                                                          **
 **  Public Prozeduren    : -----                                            **
 **                                                                          **
 **  Published Prozeduren : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Funktionen   : -----                                            **
 **                                                                          **
 **  Private Funktionen   : -----                                            **
 **                                                                          **
 **  Protected Funktionen : -----                                            **
 **                                                                          **
 **  Public Funktionen    : -----                                            **
 **                                                                          **
 **  Published Funktionen : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Globale Klassen    : FrmTestprg : TFrmTestprg                           **
 **                                                                          **
 **  Globale Konstanten : -----                                              **
 **                                                                          **
 **  Globale Variablen  : -----                                              **
 **                                                                          **
 **  Globale Records    : grTestQuery                                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Aktionen: Menuepunkte : Alle Menüpunkte werden dynamisch erstellt       **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Hinweise : keine                                                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Erstellung:                                                             **
 **                                                                          **
 **  10.00.21.1230  30.12.2021  Name des Entwicklers                         **
 **                                                                          **
 **  Aenderungen:                                                            **
 **                                                                          **
 **  10.00.21.1231  31.12.2021  Name des Entwicklers                         **
 **                 Prozedure Debug hinzugefügt                              **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 ******************************************************************************)

Packages

Code: Alles auswählen

(******************************************************************************
 **                                                                          **
 **  Package: Testpackage                                                    **
 **                                                                          **
 **  Unitname: pTest                                                         **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Erstellt dynamisch die Menues.                                          **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Prozeduren   : FormCreate(Sender : TObject)                     **
 **                         FormClose(Sender          : TObject;             **
 **                                   Var CloseAction : TCloseAction)        **
 **                                                                          **
 **  Private Prozeduren   : ppMenue(Sender : TObject)                        **
 **                         ppMenueClick(Sender : TMenuItem)                 **
 **                                                                          **
 **  Protected Prozeduren : -----                                            **
 **                                                                          **
 **  Public Prozeduren    : -----                                            **
 **                                                                          **
 **  Published Prozeduren : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Funktionen   : -----                                            **
 **                                                                          **
 **  Private Funktionen   : -----                                            **
 **                                                                          **
 **  Protected Funktionen : -----                                            **
 **                                                                          **
 **  Public Funktionen    : -----                                            **
 **                                                                          **
 **  Published Funktionen : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Globale Klassen    : FrmMenue : TFrmMenue                               **
 **                                                                          **
 **  Globale Konstanten : -----                                              **
 **                                                                          **
 **  Globale Variablen  : -----                                              **
 **                                                                          **
 **  Globale Records    : grMenue                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Aktionen: Menuepunkte : Enthält alle Menüpunkte                         **
 **            Debug       : Protokolliert die einzelnen Modulschritte       **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Hinweise : keine                                                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Erstellung:                                                             **
 **                                                                          **
 **  10.00.21.1230  30.12.2021  Name des Entwicklers                         **
 **                                                                          **
 **  Aenderungen:                                                            **
 **                                                                          **
 **  10.00.21.1231  31.12.2021  Name des Entwicklers                         **
 **                 Prozedure Debug hinzugefügt                              **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 ******************************************************************************)

Units

Code: Alles auswählen

(******************************************************************************
 **                                                                          **
 **  Unit: UTest1                                                            **
 **                                                                          **
 **  enthalten in Package: ----                                              **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Stellt mathematische Berechnungen zur Verfügung                         **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Prozeduren   : FormCreate(Sender : TObject)                     **
 **                         FormClose(Sender          : TObject;             **
 **                                   Var CloseAction : TCloseAction)        **
 **                                                                          **
 **  Private Prozeduren   : -----                                            **
 **                                                                          **
 **  Protected Prozeduren : -----                                            **
 **                                                                          **
 **  Public Prozeduren    : -----                                            **
 **                                                                          **
 **  Published Prozeduren : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Klassen Funktionen   : -----                                            **
 **                                                                          **
 **  Private Funktionen   : -----                                            **
 **                                                                          **
 **  Protected Funktionen : -----                                            **
 **                                                                          **
 **  Public Funktionen    : Multiplikation(Wert1 : Integer;                  **
 **                                        Wert2: Integer) : Integer         **
 **                                                                          **
 **  Published Funktionen : -----                                            **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Globale Klassen    : gUTest1 : TTest1                                   **
 **                                                                          **
 **  Globale Konstanten : Faktor : 100                                       **
 **                                                                          **
 **  Globale Variablen  : -----                                              **
 **                                                                          **
 **  Globale Records    : -----                                              **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Aktionen: Multiplikation : Multipliziert Wert1 mit Wert2                **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Hinweise : keine                                                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                        **
 **                                                                          **
 ******************************************************************************
 **                                                                          **
 **  Erstellung:                                                             **
 **                                                                          **
 **  10.00.21.1230  30.12.2021  Name des Entwicklers                         **
 **                                                                          **
 **  Aenderungen:                                                            **
 **                                                                          **
 **  10.00.21.1231  31.12.2021  Name des Entwicklers                         **
 **                 Prozedure Debug hinzugefügt                              **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 **                                                                          **
 ******************************************************************************)

Prozeduren

Code: Alles auswählen

    (**************************************************************************
     **                                                                      **
     **  Prozedure: FormCreate(Sender: TObject )                             **
     **                                                                      **
     **  enthalten in Unit     : FTestprg                                    **
     **  enthalten im Package  : ----                                        **
     **                                                                      **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Startet die Maske des Testprogrammes.                               **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Status: Klassenmodul [X]                                            **
     **          Private [ ]   Protected [ ]   Public [X]   Published [ ]    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Aktionen: Initialisierung : Initialisiert alle Variablen            **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Hinweise : keine                                                    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Erstellung:                                                         **
     **                                                                      **
     **  10.00.21.1230  30.12.2021  Name des Entwicklers                     **
     **                                                                      **
     **  Aenderungen:                                                        **
     **                                                                      **
     **  10.00.21.1231  31.12.2021  Name des Entwicklers                     **
     **                 Neue Variablen hinzugefügt                           **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **************************************************************************)

Funktionen

Code: Alles auswählen

    (**************************************************************************
     **                                                                      **
     **  Funktion: Multiplikation(Wert1 : Integer;                           **
     **                           Wert2: Integer) : Integer                  **
     **                                                                      **
     **  enthalten in Unit     : UTest1                                      **
     **  enthalten im Package  : Testpackage                                 **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Multipliziert Wert1 mit Wert2.                                      **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Status: Klassenmodul [ ]                                            **
     **          Private [ ]   Protected [ ]   Public [X]   Published [ ]    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Aktionen: siehe Beschreibung                                        **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Hinweise : keine                                                    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  aktuelle Version: 10.00.21.1231  vom  31.12.2021                    **
     **                                                                      **
     **************************************************************************
     **                                                                      **
     **  Erstellung:                                                         **
     **                                                                      **
     **  10.00.21.1230  30.12.2021  Name des Entwicklers                     **
     **                                                                      **
     **  Aenderungen:                                                        **
     **                                                                      **
     **  10.00.21.1231  31.12.2021  Name des Entwicklers                     **
     **                 Prüfung auf Negativzahlen                            **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **                                                                      **
     **************************************************************************)

[charlytango]

ist IMHO Geschmackssache - und wohl auch davon abhängig ob und welchen Documenter man benutzt.
Welche benutzt ihr ?

PasDoc wäre evtl ein Kandidat

[PascalDragon]

Entweder ich dokumentiere Funktionalitäten auf PasDoc Art zusammen mit den Klassen, Methoden, Funktionen, etc. oder im FpDoc Style in 'ner komplett separaten Datei.

Da ich 'ne Versionsverwaltung einsetze sind auch Änderungen dort ersichtlich.

Das heißt der Header beschränkt sich bei mir rein auf die Lizenz und eventuell noch eine Beschreibung der Unit allgemein.

[Winni]

Hi

Zu PasDoc hat sich mal jemand in diesem Forum viel Mühe gemacht:

viewtopic.php?t=516

Winni