So konfigurieren Sie Doxygen, um Objective-C-Kategorien richtig zu dokumentieren

Question

Doxygen scheint idiosynkratische Behandlung von Objective-C-Kategorien zu haben, und ich würde gerne wissen, ob andere erfolgreich damit umgehen konnten. Ich möchte, dass doxygen alle Kategorien einer Klasse als separate Entitäten dokumentiert, unabhängig davon, ob die Basisklasse dokumentiert ist oder nicht.

Wenn ich doxygen Markup zu einer Kategorie auf einer undokumentierten Basisklasse hinzufügen - sagen NSString, dann listet doxygen die Kategorie und ihre Methoden in der Klassenliste als separate Entität.

/** 
* @category NSString(Foo) 
* @brief A sample category on NSString 
*/ 
@interface NSString(Foo) 
@end 

Ergebnisse in einer dokumentierten Entität NSString (Foo) in der Klassenliste.

Aber das folgende Beispiel nicht:

/** 
* @category CCFMyCustomClass(Foo) 
* @brief A category on a documented base class 
*/ 
@interface CCFMyCustomClass(Foo) 
@end 

Stattdessen im letzteren Fall alle Methoden auf CCFMyCustomClass (Foo) sind in der Dokumentation für CCFMyCustomClass enthalten - die Basisklasse.

Die folgende, wenn auch oft zitiert, scheint nicht mit diesem Problem zu helfen:

• Doxygen and Objective-C categories

• http://www.duckrowing.com/2010/03/18/documenting-objective-c-with-doxygen-part-i/

Answer 1

Sie könnten Doxygen überspringen und mit AppleDoc gehen.

appledoc ist ein Befehlszeilentool, das Objective-C-Entwicklern bei der Erstellung von Apple-ähnlicher Quellcodedokumentation aus speziell formatierten Quellcode-Kommentaren hilft. Es wurde entwickelt, um möglichst lesbare Quellcode-Kommentare für die Eingabe zu nehmen und Kommentare sowie umgebenden Quellcode zu verwenden, um visuell ansprechende Dokumentation in Form von HTML sowie vollständig indizierten und durchsuchbaren Xcode-Dokumentationssatz zu generieren. Obwohl es mehrere Tools gibt, die HTML-Dokumentation für Objective-C erstellen können, sind alle, die ich kenne, nicht in der Lage, die unten beschriebenen Mindestanforderungen zu erfüllen.

Es ist auch auf GitHub

Answer 2

Eine Lösung, wenn auch nicht ideal ist, Erstellen Sie eine Gruppe für die Kategoriemethoden, sodass sie zumindest auf der Dokumentationsseite der Basisklasse gruppiert sind.

So das zweite Beispiel entspricht, oben:

/** @name CCCFMyCustomClass(Foo) 
      Methods defined only in CCFMyCustomClass(Foo) category */ 
//@{ 

/** 
* 
* @method someFooMethod 
* @brief Does some foo things 
* @details First foo, then more foo, etc. 
*/ 
- (void)someFoodMethod; 

//@} 

Abgesehen davon, dass ich kein anderes Mittel, Aussondern Kategorien auf einer dokumentierten Basisklasse gefunden habe.

Answer 3

ich in einer anderen Stimme für Appledoc werfen möchten. Es ist viel einfacher, für Objective-C gute Ergebnisse zu erzielen als Doxygen.

Answer 4

dokumentiere ich meine Klassen (in den Header-Dateien) wie:

/** 
@interface MyAppDelegate 
@mainpage The iPhone App 

This is information about my app, and appears in the main HTML page.\n\n 

As with all iOS apps, the main entry point is an App Delegate @see MyAppDelegate 
@defgroup Classes Classes 
@{ 
@brief Miscellaneous Classes 

Classes that don't fit in any other category 
@{ 
*/ 
/** 
@brief The application's delegate 

A delegate object is instantiated by the main function, so this is effectively the main entry point for the app 
@see MyAppDelegate() 
*/ 
@interface MyAppDelegate : UIResponder <UIApplicationDelegate> 
... 
@end 

/** @} */ 

/** @} */ 

The.m Datei hat eine Erweiterungskategorie, in der ich meine privaten Erweiterungsmethoden habe. Das sieht aus wie:

/** 
@category MyAppDelegate(internal) 
@addtogroup Classes 
@{ 
*/ 

/** 
@brief Application delegate class extension 

Internal extension for the application delegate 
@see MyAppDelegate 
*/ 
@interface MyAppDelegate() 
... 
@end 

/** @} */ 

@implementation MyAppDelegate 
... 
etc 

ich zwei HTML-Seiten erhalten - für MyAppDelegate und MyAppDelegate() Der Erste, der eine für die zweite siehe-auch enthält, obwohl die see-auch in der zweiten zurück in die erste nicht funktioniert (Es scheint, als gäbe es ein Problem mit @see category(). Allerdings sind die Methoden korrekt zwischen den beiden Seiten aufgeteilt.

Ich denke, der Schlüssel ist, nur Ihre Methoden innerhalb der Objective-C @ Interface-Blöcke nicht innerhalb zu dokumentieren die @ implementation blocks.Ich benutze auch @defgroup und @addtogroup-Blöcke, um alle Module eines bestimmten Typs (wie View-Controller, Modelle und so weiter).

Ich hoffe, das hilft jemandem