Objective-C 方法描述（文档注释）

Question

我目前正在学习 Objective-C，需要知道如何编写方法描述。我在学习如何在 Objective-C 中做到这一点时遇到了很多困难。

在 Jave 中我们有这个

/**
< h2 >MethodName</ h2 >
< p >Various Description, can use html with images etc.</ p >
*/
private void methodName(args[]..)
{

} 

在objective-c中我在哪里放置描述？这也是在头文件中还是在实现文件中？

//Within Implementation?
- (float)gteHeightPercentage:(float)percentageToGet
{
    return self.view.bounds.size.height * percentageToGet;
}

//Within Header?
- (float)getWidthPercentage:(float)percentageToGet;

Answer 1

您所描述的称为“文档 cmets”，或简称为“doc cmets”。

从 4.6.3 版开始，Xcode 不会在弹出窗口或其快速帮助检查器中显示您自己的 doc cmets。你必须将你的 cmets 编译成一个“文档集”才能让 Xcode 显示它们。有工具可以做到这一点，但没有办法让 Xcode 重新加载文档集，除非退出并重新启动它，所以我不建议打扰。

Xcode 5（目前可作为 OS X 和 iOS 开发者计划的付费会员的开发者预览版）确实显示您自己的代码的 doc cmets；见“Quick Help” on the Developer Tools Features page。您必须在头文件中写入 doc cmets。您可以使用 doxygen 或 headerdoc 格式。

Answer 2

在objective-c中我应该把描述放在哪里？

像 gcc 和 llvm 这样的 Objective-C 编译器并不关心你如何记录你的代码。有几种不同的文档生成器，例如 Doxygen 和 HeaderDoc，它们可以从适当格式的 cmets 构建文档，通常在您的头文件中。此外，Xcode 可以轻松跳转到代码中定义的符号定义，并且它的“快速帮助”检查器可以显示定义，无需在代码中添加任何特殊注释。

Answer 3

更新：以下格式适用于Objc。如果你想记录swift代码，请参考NSHipster's blog about Swift Documentation

Xcode 5 可以做你想做的事。感谢Wonil Kim，在 .h 文件中：

/** 
 * Add new message between source to destination timeline as empty name string
 * @author Wonil Kim
 *
 * @param sourceId Source timeline entity ID
 * @param destId Destination timeline entity ID
 * @return A newly created message instance
 */
- (ISMessage*)messageFromTimeline:(NSInteger)sourceId toTimeline:(NSInteger)destId;

完成后，您可以alt+点击方法名称，然后..瞧！

当然，正如您在 Kim's blog 上看到的那样，这不是唯一的方法：

/*! Some description of the method....
 * \returns  The result
 */

或者，

/// Some description to show up, done by:
/// @author  Olly Dixon

你明白了……

正如许多人已经提到的，Objective-C 不会向您展示您的文档；事实上，java 也不是（javadoc，可能是）。这是你的 IDE，在这种情况下，是不可崩溃的 Xcode :)

UPDATE2： Complete list of "Special Commands" in comments.

UPDATE3：如果您想启用/// 自动生成文档，请使用VVDocumenter-Xcode。

UPDATE4：：VVDocumenter 已集成到 Xcode：

使用快捷键（⌥ Option + ⌘ Command + /）添加文档 如果您使用的是 Xcode 8 或更高版本，请对您的代码进行注释