Question

是否有关于如何记录用XCode编写的代码的指南/标准？我的意思是，有没有办法记录代码，如果你想让其他人容易理解？ XCode是否提供了一种工具，可用于从代码+注释中自动生成API参考文档等文档？

至少我有兴趣了解在代码中定义的接口/协议/方法之前是否存在编写注释的标准方法。我见过使用类似下面的指令，但我不明白它们是如何工作的：

#pragma mark -
#pragma mark Initialization

Answer 1

您可以将这两行合并为一个：#pragma mark - Initialization。单击方法列表（向上，向右），您将看到带有一行的粗体标题。它只是分组中方法分组的标记。

以上Derek发布的编码指南链接必读。

如果你想制作类似苹果的文档，你必须使用这个优秀的免费第三方工具：http://www.gentlebytes.com/appledoc/ Apple没有为你提供任何接近它的东西。

Pragma是一种ISO C功能，可以将提示传递给编译器。

XCode（AFAIK）中唯一添加的pragma是带有mark和/或文本的-。这会在方法查找器中创建一行和/或粗体文本。

// Mark a section in your code with a line and a bold text.
// You can use the line or the text alone.
#pragma mark - random text

如果您正在编辑不使用GCC编译的语言的文件，您仍然可以在评论上使用标记（这也适用于GCC语言）：

// MARK: - random text
/* MARK: more random text */

但是我使用#pragma mark，因为我的颜色主题是红色的pragma，它们比评论更突出。如果您想将pragma代码段绑定到热键，请使用

#pragma mark - <#Description#>

因此您可以跳转到说明文字。

关于pragma的更多信息：

What is a pragma?
6.56 Pragmas Accepted by GCC
Clang的Controlling Diagnostics via Pragmas
Function attributes比pragma更受欢迎，因为你不能从宏生成编译指示，而pragma可能在另一个编译器上有不同的含义。

Answer 2

添加@ jano的答案，请使用以下格式来描述您方法的功能。

  /*!
 @function       getEmployeeDetails
 @abstract       getEmployeeDetails
 @discussion     This function will fetch employee details based on employee id
 @param          strEmpId 
 employee unique id
 @result         an Array of Employee
 */

-(NSArray*)getEmployeeDetails:(NSString *)strEmpId{
     /*Do somethings.*/
}

Xcode代码文档

2 个答案: