Funktions­beschreibung und Datei­header per Makro

Beschreibung des Makros "Generate­File­Comment()"

Typischerweise beginnen alle Quelltextdateien in einem Projekt mit einem Kommentarblock, der den Inhalt der Datei, Name und Zweck, Erstellungsdatum usw. enthält. Dieses Makro erzeugt diesen Block automatisch am Anfang der aktuell geöffneten Datei.

Beispiel für einen erzeugten Dateikopf (File header):

//---------------------------------------------------------
// My company name or private copyright notice
//
// Filename:     test.cpp
// Created:      2005-12-04 (17:52), by Andreas Schibilla
// Purpose:
//
// Coypright(c): Andreas Schibilla
//---------------------------------------------------------

Beschreibung des Makros "Generate­Function­Comment()"

Auch vor jeder Funktionsdefinition sollte ein Kommentarblock stehen, der die Funktion, die Parameter, den Rückgabewert usw. erläutert.
Dieses Makro erstellt diesen Kommentarblock mit der Funktionsbeschreibung automatisch, so dass nur noch die wesentlichen Angaben hinzugefügt werden müssen.

Funktionsweise 1:

Der Cursor wird einfach in die Kopfzeile der Funktion gesetzt, dann wird das Makro gestartet, der Kommentarblock wird automatisch eingefügt.

Beispiel:
Befindet sich der Cursor irgendwo in der untenstehenden Zeile:

int test(int a, void *pointer , unsigned int my_funny_array[] )

So erzeugt das Makro den neuen Text:

//------------------------------------------------------------------
// Function:     test()
// Description:
// Returns:      -
//
// Parameters:
// [->] a              -
// [->] pointer        -
// [->] my_funny_array -
//
// Created:      2005-12-04 (18:55), by Andreas Schibilla
//------------------------------------------------------------------
int test(int a, void *pointer , unsigned int my_funny_array[] )

Funktionsweise 2:

Geht der Funktionskopf über mehrere Zeilen, so muss der komplette Funktionskopf entsprechend markiert werden, bevor das Makro gestartet wird.

Beispiel:
Die untenstehenden drei Zeilen sind markiert:

template
T maximum( T const a,
           T const b ){ return a > b ? a : b; }

Das Makro erzeugt dann den Textblock:

//------------------------------------------------------------------
// Function:     maximum()
// Description:
// Returns:      -
//
// Parameters:
// [->] a -
// [->] b -
//
// Created:      2005-12-04 (19:05), by Andreas Schibilla
//------------------------------------------------------------------
template
T maximum( T const a,
           T const b ){ return a > b ? a : b; }

Funktionsweise 3:

Wenn eine Funktion bereits einen Beschreibungstext hat, kann durch erneutes Aufrufen des Makros ein "Modified" mit aktuellem Datum hinzugefügt werden.

Beispiel:
Der Cursor befindet sich irgendwo in der untersten Zeile (beginnend mit "void MyClass...") des folgenden Codeausschnitts:

//------------------------------------------------------------------
// Function:     MyFunction()
// Class:        MyClass
// Description:  Some text to explain function
// Returns:      -
//
// Created:      2005-12-04 (19:09), by Andreas Schibilla
//------------------------------------------------------------------
void MyClass::MyFunction()

Dann erzeugt ein Aufruf des Makros den zusätzlichen "Modified-Eintrag":

//------------------------------------------------------------------
// Function:     MyFunction()
// Class:        MyClass
// Description:  Some text to explain function
// Returns:      -
//
// Created:      2005-12-04 (19:09), by Andreas Schibilla
// Modified:     2005-12-04 (19:12), by Andreas Schibilla
//------------------------------------------------------------------
void MyClass::MyFunction()