Funktionsdokus ============== Der grundsätzliche Aufbau der Dokumentation einer Lfun ------------------------------------------------------ /* FUNKTION: funktionsname DEKLARATION: static varargs mixed funktionsname(string parameter, ...) BESCHREIBUNG: Hier kommt die eigentliche Dokumentation der Funktion. VERWEISE: weitere, funktionsnamen GRUPPEN: Gruppe1, Gruppe2 */ Zu den einzelnen Elementen -------------------------- Kommentar: Die Doku wird mit einem /*, welches am Zeilenanfang beginnen muss, eingeleitet. In der nächsten Zeile muss unmittelbar der Eintrag 'FUNKTION:' folgen. Abschließen muss die Doku mit einem */, welches ebenfalls am Zeilenafang steht. FUNKTION: Dieser Eintrag wird gefolgt vom Funktionsnamen. Dieser Name darf wie in LPC nur aus Buchstaben, Zahlen oder Unterstrichen bestehen. DEKLARATION: Hier kommt die Deklaration der Funktion. Sie ist auch bei Überlänge in einer Zeile zu schreiben. Man muss nicht die Originaldeklaration nehmen, sondern kann sie etwas verständlicher machen. (z.B. statt 'mixed arg' könnte man 'string file|object ob' schreiben, oder durch eine eckige Klammer andeuten, dass ein Parameter optional ist.) Man sollte jedoch die Modifier (nomask, static, private, varargs etc.) beibehalten. BESCHREIBUNG: Unmittelbar nach der Deklaration beginnt mit diesem Eintrag die eigentliche Doku. Es ist zwar erlaubt, direkt hinter 'BESCHREIBUNG: ' noch in dieser Zeile mit der Doku zu beginnen, schöner ist es jedoch, mit einer neuen Zeile anzufangen. VERWEISE: Die durch Kommata getrennten Verweise können sich über mehrere Zeilen erstecken und sollten auf andere Funktionen (Lfuns oder Efuns) verweisen. Um von einer Lfun auf eine Efun (oder umgekehrt) zu verweisen, kann man dem Funktions- namen den Präfix 'efun::' (bzw. 'lfun::') voranstellen. Verweise auf Dateien sind nicht gern gesehen (und werden vom WWW-Script fehlerhaft verarbeitet). Dieser Eintrag ist optional. GRUPPEN: Hier folgt eine durch Kommata getrennte Auflistung von Gruppen, denen diese Funktion zugerechnet wird. Diese Auflistung kann sich ebenfalls über mehrere Zeilen erstrecken. Was alles als Gruppe zählt, dazu weiter unten mehr. Es sollte mindestens eine Gruppe eingetragen sein. SOURCE: Dieser Eintrag ist optional und sollte nur selten eingesetzt werden. Falls eine Dokumentation für Implementationen in verschiedenen Dateien gilt, so kann man damit die anderen Dateien angeben, die ebenfalls diese Funktion implementieren. Jede Datei hat auf einer einzelnen Zeile (jeweils mit einem 'SOURCE: ' davor) zu stehen. Die Reihenfolge der Einträge bis zu BESCHREIBUNG ist genau einzuhalten. Da restlichen Einträge (VERWEISE, GRUPPEN, SOURCE) können in beliebiger Reihenfolge auftauchen, es wird der Übersichtlichkeit halber aber empfohlen, obige Reihenfolge zu übernehmen. Die Gruppen ----------- Es gibt 3 Arten von Gruppen, welche in der Doku angegeben werden können: - ACL-Gruppen: Ein Gott, welcher direktes oder indirektes Mitglied dieser Gruppe oder einer seiner Untergruppen ist, sieht diese Funktion. - Virtuelle Gruppen: Man kann eine ACL-Gruppe einfach um Untergruppen erweitern. Ein Gott, welcher direktes oder indirektes Mitglied dieser ACL-Gruppe ist, sieht diese Funktion. - Gruppennamen, welche keine ACL-Gruppen sind und auch keine Doppelpunkte haben: Jeder Gott sieht diese Funktion. Funktionen, welche nicht für das öffentliche Interesse bestimmt sind, sollten daher ausschliesslich(!) Gruppen der 1. und 2. Kategorie nutzen. Ausnahmen von diesen Regeln kann jeder Gott für sich mit dem (no)listgroup-Befehl definieren. Zur Schreibweise: ACL-Gruppen und virtuelle Gruppen sollten so geschrieben werden, wie sie angemeldet sind. Gruppen der 3. Kategorie sollten klein oder mit großen Anfangsbuchstaben geschrieben werden. (Dies ist keine Pflicht, falls man aber von dieser Regel abweicht, sollte man diese Gruppe überall einheitlich schreiben.) Die Gruppen 'Texte', 'Funktionen', 'Statistiken', 'Deklarationen', 'WasIstWo' und 'WoIstWas' sind tabu. Enzy-Direktiven --------------- Beim Einlesen der Dokumentation werden folgende Direktiven erkannt: // ENZY: KEINE -> Das Einlesen der Doku dieser Datei wird an dieser Stelle abgebrochen // ENZY: GRUPPEN: Gruppe1, Gruppe2 -> Falls eine Doku keinen GRUPPEN-Eintrag besitzt, werden diese Gruppen dort eingetragen. Sonstiges --------- Die Doku wird jeden Sonntag morgen aus allen Dateien im /d, /p und /z, welche die Endung .c, .h oder .inc haben oder API heißen, eingelesen. Verzeichnisse mit dem Namen OLD, Old, TEST oder NEU werden ignoriert. Fehlermeldungen beim Einlesen werden nach /log/sys/DOKU geschrieben. Die Dokumentation aus dem /d, /p und /z ist nicht im öffentlichen muddocs.tar.gz enthalten. Stattdessen gibt es ein /tar/Doc/doc.tar.gz mit diesen Dokus.