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

Question

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

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

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

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

Solution 1

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

/*!
 * 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:

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

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

Solution 2

What I have found to be better than a code snippet for Doxygen/Javadoc style comments is using VVDocumenter-Xcode Plugin It 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.

Solution 3

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

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.

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

Comments

[CodaFi]

Documentation in the auto completion popover prior to XDACTED 5 is hard-coded into the IDE because CLANG 5 was the first to introduce a parser for that stuff.

[antonicelli]

@CodaFi Does that mean that I can't get popover completition for custom methods?

[CodaFi]

Nope, not without some serious hacking in IDEKit.

[memmons]

Can now be done with Xcode 5. See answer below. One of my fav new Xcode 5 features

[memmons]

@reecon Copy/paste it into your code view, highlight it and drag-drop into the code snippet area.

[aqavi_paracha]

I can't see "Doxygen method documentation" template in xcode 5. Any clue on why?

[memmons]

@aqavi_paracha There is no such default template, it's a user created one.

[Chen Li Yong]

Thank you for the <#...#> thing. I learn something new today.