20

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

img

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.

4
  • 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.
    – CodaFi
    Aug 17, 2013 at 19:40
  • @CodaFi Does that mean that I can't get popover completition for custom methods? Aug 17, 2013 at 19:43
  • Nope, not without some serious hacking in IDEKit.
    – CodaFi
    Aug 17, 2013 at 19:44
  • Can now be done with Xcode 5. See answer below. One of my fav new Xcode 5 features
    – memmons
    Nov 12, 2013 at 3:00

3 Answers 3

52

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:

inline help



Quick help will look like this:

quick help



And sidebar help will look like this:

sidebar help

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

doxygen code snippet

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

4
  • 2
    @reecon Copy/paste it into your code view, highlight it and drag-drop into the code snippet area.
    – memmons
    Dec 16, 2013 at 15:58
  • I can't see "Doxygen method documentation" template in xcode 5. Any clue on why? Jan 28, 2014 at 13:44
  • 1
    @aqavi_paracha There is no such default template, it's a user created one.
    – memmons
    Jan 28, 2014 at 16:26
  • Thank you for the <#...#> thing. I learn something new today. Nov 25, 2016 at 4:51
3

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.

2

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

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.