如何在 Xcode 的自动完成弹出窗口中包含 Doxygen 方法描述？

How to include Doxygen method description in Xcode's autocomplete popup?

提问by antonicelli

Using Xcode , I want to have the Doxygen description of my method below the autocomplete option, like alloc:

使用 Xcode ，我希望在自动完成选项下方对我的方法进行 Doxygen 描述，例如alloc：

When writing, Xcode displays the autocomplete with the comments from the documentation. You can see in the image for example, when allocis selected from the options, it says "Returns a new instance of the receiving class" and also links to the documentation.

编写时，Xcode 会显示带有文档注释的自动完成功能。例如，您可以在图像中看到，当alloc从选项中选择时，它会显示“返回接收类的新实例”并链接到文档。

I have been able to document my source code with Doxygen, for instance

例如，我已经能够用 Doxygen 记录我的源代码

/** 
 This does nothing
*/
 -(void) doNothing
{
    // This does nothing
}

and I get the expected results in the HTML file that Doxygen generates, yet I don't know how to make those results appear as suggestions in Xcode.

我在 Doxygen 生成的 HTML 文件中得到了预期的结果，但我不知道如何让这些结果在 Xcode 中显示为建议。

回答by memmons

Good news everyone! Xcode 5 now has built-in support for DOxygen style comments. So, you can comment your methods like this:

大家好消息！Xcode 5 现在内置了对 DOxygen 样式注释的支持。所以，你可以像这样评论你的方法：

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;

Inline help will look like this:

内联帮助将如下所示：

Quick help will look like this:

快速帮助如下所示：

And sidebar help will look like this:

侧边栏帮助将如下所示：

Here's a handy code snippet you can add the your Xcode Code Snippet library to make method documentation simple:

这是一个方便的代码片段，您可以添加 Xcode 代码片段库以简化方法文档：

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

Now, you can just type "doxy" and poof! You have your doxygen template.

现在，您只需输入“doxy”然后噗！你有你的 doxygen 模板。

回答by Josh

What I have found to be better than a code snippet for Doxygen/Javadoc style comments is using VVDocumenter-Xcode PluginIt is great! After installing you can simply type "///" above any code you want commented and it will grab the parameters and return as well add placeholders for you to complete your comment block.

我发现比 Doxygen/Javadoc 样式注释的代码片段更好的是使用VVDocumenter-Xcode 插件它很棒！安装后，您只需在要注释的任何代码上方键入“////”，它就会获取参数并返回，并为您添加占位符以完成注释块。

回答by antonicelli

I was able to achieve what I wanted using Appledocs, although I fought a bit with installation and setup...

我能够使用 Appledocs 实现我想要的东西，尽管我在安装和设置方面有点挣扎......

1. Open xCode and go to xCode> Preferences > Downloads and download the 'Command Line Tools' in case you don't have it.

2. Open up terminal and type

   git clone git://github.com/tomaz/appledoc.git
   

3. When it's done go to the appledoc folder, type

   cd appledoc
   

   and install appledoc into your usr/local/bin folder with this command:

   sudo sh install-appledoc.sh 
   

4. Open any xCode project and go to the package explorer on the left, and click on your main project file (the one that has the amount of targets and the sdk version detailed below)

5. In the Build settings tab, look below for '+Add Target' button and open it

6. Choose the 'Aggregate' template (make sure you choose iOS or macosx depending on your project and name it 'Documentation'

7. Select Documentation, go to Build Phases tab, and below click 'Add Build Phase' and select Add Run Script.

8. Copy and paste the code below on the Run Script field:

   #appledoc Xcode script
   # Start constants
   company="ACME";
   companyID="com.ACME";
   companyURL="http://ACME.com";
   #target="iphoneos";
   target="macosx";
   outputPath="~/help";
   # End constants
   /usr/local/bin/appledoc \
   --project-name "${PROJECT_NAME}" \
   --project-company "${company}" \
   --company-id "${companyID}" \
   --docset-atom-filename "${company}.atom" \
   --docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
   --docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
   --docset-fallback-url "${companyURL}/${company}" \
   --output "${outputPath}" \
   --publish-docset \
   --docset-platform-family "${target}" \
   --logformat xcode \
   --keep-intermediate-files \
   --no-repeat-first-par \
   --no-warn-invalid-crossref \
   --exit-threshold 2 \
   "${PROJECT_DIR}"
   

9. In the start constants, you can replace names and such, also make sure to use the proper target (iOS or macosx)

10. Finally, go to Product > Scheme > Edit Scheme > Build Tab and add your 'Documentation' Target, make sure every box is checked. This way each time you build your code your documentation gets updated.

1. 打开 xCode 并转到 xCode> 首选项 > 下载并下载“命令行工具”，以防您没有它。

2. 打开终端并输入

   git clone git://github.com/tomaz/appledoc.git
   

3. 完成后转到appledoc文件夹，输入

   cd appledoc
   

   并使用以下命令将 appledoc 安装到您的 usr/local/bin 文件夹中：

   sudo sh install-appledoc.sh 
   

4. 打开任何 xCode 项目并转到左侧的包资源管理器，然后单击您的主项目文件（包含目标数量和 sdk 版本的文件如下所述）

5. 在构建设置选项卡中，查看下方的“+添加目标”按钮并打开它

6. 选择“聚合”模板（确保根据您的项目选择 iOS 或 macosx 并将其命名为“文档”

7. 选择“文档”，转到“构建阶段”选项卡，然后在下方单击“添加构建阶段”并选择“添加运行脚本”。

8. 将以下代码复制并粘贴到“运行脚本”字段中：

   #appledoc Xcode script
   # Start constants
   company="ACME";
   companyID="com.ACME";
   companyURL="http://ACME.com";
   #target="iphoneos";
   target="macosx";
   outputPath="~/help";
   # End constants
   /usr/local/bin/appledoc \
   --project-name "${PROJECT_NAME}" \
   --project-company "${company}" \
   --company-id "${companyID}" \
   --docset-atom-filename "${company}.atom" \
   --docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
   --docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
   --docset-fallback-url "${companyURL}/${company}" \
   --output "${outputPath}" \
   --publish-docset \
   --docset-platform-family "${target}" \
   --logformat xcode \
   --keep-intermediate-files \
   --no-repeat-first-par \
   --no-warn-invalid-crossref \
   --exit-threshold 2 \
   "${PROJECT_DIR}"
   

9. 在开始常量中，您可以替换名称等，还要确保使用正确的目标（iOS 或 macosx）

10. 最后，转到产品 > 方案 > 编辑方案 > 构建选项卡并添加您的“文档”目标，确保选中每个框。这样每次构建代码时，文档都会更新。

And that's it, you are good to go and start documenting your code. Note that although the documentation updates each time you build, the popover suggestions won't update until you restart Xcode. For proper documentation techniques, read this article

就是这样，您很高兴开始记录您的代码。请注意，尽管每次构建时文档都会更新，但在您重新启动 Xcode 之前，弹出窗口建议不会更新。有关正确的文档技术，请阅读本文