如何配置 Doxygen 以正确记录 Objective-C 类别答案

【问题标题】：How to configure Doxygen to document Objective-C categories properly如何配置 Doxygen 以正确记录 Objective-C 类别
【发布时间】：2011-06-03 13:40:14
【问题描述】：

Doxygen 似乎对 Objective-C 类别有特殊处理，我想知道其他人是否能够成功解决它。我希望 doxygen 将类中的所有类别记录为单独的实体，无论基类是否已记录。

如果我将 doxygen 标记添加到 undocumented 基类上的类别（例如 NSString），则 doxygen 会将类别及其方法在类列表中列为单独的实体。

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

在类列表中生成一个记录的实体 NSString(Foo)。

但是，下面的例子没有：

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

相反，在后一种情况下，CCFMyCustomClass(Foo) 上的所有方法都包含在 CCFMyCustomClass（基类）的文档中。

以下内容虽然经常被引用，但似乎对解决这个问题没有帮助：

【问题讨论】：

标签： objective-c doxygen categories

【解决方案1】：

您可以跳过 Doxygen 并使用 AppleDoc。

appledoc 是命令行工具，可帮助 Objective-C 开发人员从特殊格式的源代码 cmets 生成类似 Apple 的源代码文档。它旨在将尽可能可读的源代码 cmets 用于输入，并使用 cmets 以及周围的源代码以 HTML 的形式生成具有视觉吸引力的文档以及完全索引和可浏览的 Xcode 文档集。尽管有几种工具可以为 Objective-C 创建 HTML 文档，但我所知道的所有工具都无法满足下面描述的最低目标。

也可以通过GitHub获得

【讨论】：

谢谢 - AppleDoc 看起来更适合（当然）ObjC 和 Cocoa 范例。将不得不从广泛的 Doxygen 标记中查看迁移路径。
请注意，appledoc 与 doxygen 不同，需要归因。
@FeloneousCat 这是个问题，因为……？
AppleDoc 的灵活性要低得多，并且省略了枚举和 C++ 文件。我不建议迁移到它。
我完全同意@IliasKarim。我使用过 Doxygen 和 Appledoc，但前者要好得多。 Doxygen 最好的部分是您可以集成 Graphviz 来生成点文件。

【解决方案2】：

一种解决方案虽然不理想，但为类别方法创建一个组，以便至少在基类文档页面上将它们分组在一起。

所以符合上面第二个例子：

/** @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;

//@}

除此之外，我没有发现其他方法可以在记录的基类上分离类别。

【讨论】：

【解决方案3】：

我想再次为 Appledoc 投一票。 Objective-C 比 Doxygen 更容易获得好的结果。

【讨论】：

【解决方案4】：

我记录我的类（在头文件中），例如：

/**
 @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

/** @} */

/** @} */

.m 文件有一个扩展类别，其中我有我的私有扩展方法。这看起来像：

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

/**
 @brief Application delegate class extension

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

/** @} */

@implementation MyAppDelegate
...
etc

我得到两个 html 页面 - MyAppDelegate 和 MyAppDelegate() 第一个包含第二个的 see-also，尽管第二个返回到第一个的 see-also 不起作用（看起来有问题使用@see category()。但是方法在两个页面之间正确拆分。

我认为关键是只在Objective-C @interface 块内记录您的方法，而不是在@implementation 块内。我还使用 @defgroup 和 @addtogroup 块将某种类型的所有模块（如视图控制器、模型等）组合在一起。

我希望这对某人有所帮助

【讨论】：