Documenting your code in Xcode 4

Introduction

If you are like me – beginning with programming in Objective-C in Xcode and you were Java programmer previously, you will wonder how to write code comments in a similar way to JavaDoc.

Well, Apple obviously thinks that programmers do not need to write documentation. Otherwise they would implement a similar documentation tool such as Javadoc and do not force programmers to do nasty hacks to be able to do so.

However there is a way, even though it requires a few manual steps. This blog post is a step-by-step how-to guide to prepare your Mac OS X 10.7 and Xcode 4.3 to be able to generate documentation out of your code and let Xcode offer that documentation to you through its Organiser and also through Quick Help in Utilities area.

Xcode 4 Quick Help

Xcode 4 Quick Help

Prepare the Appledoc application

We will need to build the Appledoc application as there is no official OS X package available. After having the binary builded we will need to distribute the binary and also a couple of templates required to build HTML documentation files into our system.

Check out the Appledoc web

Walk through Gentle Bytes website. We will use this free tool (BSD license) to generate documentation out of our source files.

Syntax of the code comments is described on Gentle Bytes comments page.

Clone github repository

We need to download the application in order to build it. Go into the directory where you hold Xcode projects and then type following command in Termial application:

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

This command will create appledoc directory and clone the project’s GIT repo there.

Build the application

Open the appledoc.xcodeproj file in Xcode.

Edit your Scheme by clicking Xcode menu > Product > Edit Scheme menu item (Cmd + <) and change the Build Configuration to Release.

Build Configuration

Build Configuration

Build the project to get an executable binary.

Install the aplication

Let Xcode open the location of built appledoc executable.

Show appledoc in Finder

Show appledoc in Finder

You can also find the location manually, just search in ~/Library/Developer/Xcode/DerivedData/ for appledoc directory with some randomly-generated suffix. Copy the appledoc executable into the /Applications directory. Having the executable in the /Applications directory will allow Xcode to run the tool as a build script.

appledoc binary location

appledoc binary location

Prepare documentation templates for use

Appledoc application requires a couple of templates to be able to generate Xcode documentation. Goto the appledoc directory (the one created by GIT in previous step) and copy the content of Templates sub-directory into ~/Library/Application Support/appledoc/. This is the default location the application searches for its templates in.

Appledoc templates

Appledoc templates

Configure your project

To ease our life we will configure our Xcode projects so that when we build our applications the documentation will be generated automatically as well as Xcode will be informed that the documentation was updated.

Create configuration file

Add this configuration file into your Xcode project directory and name it AppledocSettings.plist. Do not forget to change the red-marked options according to your needs. You can also play with the other options as well. More information can be found on the Gentle Bytes settings page.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>--company-id</key>
<string>com.yourcompanysite</string>
<key>--create-docset</key>
<true/>
<key>--ignore</key>
<array>
<string>ThirdParty</string>
<string>Libraries</string>
<string>Frameworks</string>
<string>Testing</string>
</array>
<key>--install-docset</key>
<true/>
<key>--docset-platform-family</key>
<string>macosx</string>
<key>--output</key>
<string>/tmp</string>
<key>--project-company</key>
<string>YourCompanyName</string>
<key>--project-name</key>
<string>YourProjectName</string>
<key>--project-version</key>
<string>YourDocumentationVersion</string>
<key>--keep-undocumented-objects</key>
<true/>
<key>--keep-undocumented-members</key>
<true/>
<key>--warn-undocumented-object</key>
<false/>
<key>--warn-undocumented-member</key>
<false/>
<key>--warn-empty-description</key>
<true/>
<key>--warn-missing-arg</key>
<true/>
<key>--warn-unknown-directive</key>
<true/>
<key>--logformat</key>
<string>xcode</string>
<key>--exit-threshold</key>
<integer>2</integer>
</dict>
</plist>

Create documentation target

Add a new target into your Xcode project (Mac OS X/Other/Aggregate target) and name it Documentation. The new target will allow us to get the documentation generated every time we build our projects.

Xcode 4 targets

Xcode 4 targets

Aggregate target

Aggregate target

Add new Run Script

Add Run Script build phase into the Documentation target. The Run Script will give us a chance to enter shell script to run the Appledoc application and pass commands over to it.

Adding Run Script Build Phase

Adding Run Script Build Phase

Configure Run Script

Add the shell script below into the Run Script shell command place.

# Build an Xcode documentation
/Applications/appledoc "$SOURCE_ROOT/$PROJECT_NAME"
Custom shell script

Custom shell script

Set up the build scheme

Add Documentation target into the existing scheme so that the documentation is created every time you build your project. You can reach the screen below by clicking Xcode menu > Product > Edit Scheme menu item (Cmd + <).

Build Scheme

Build Scheme

Enjoy :-)

Every time you will build your project the documentation will be generated automatically and will be pushed to Xcode so you can start using your documentation immediately.

The only issue with Xcode 4 is it does not reload Quick Help cache upon documentation changes. The only way to get it reloaded is to restart Xcode. In Xcode 3, it was possible to reload the documentation by running an AppleScript command below. However, it does not work in Xcode 4 anymore.

tell application "Xcode"
  load documentation set with path
  "/Users/YourUserName/Library/Developer/Shared/Documentation/DocSets/
    com.yourcompanysite.YourProjectName.docset"
end tell

If you are interested to see the output documentation files the Appledoc tool creates, go to the directory below.

~/Library/Developer/Shared/Documentation/DocSets/

About these ads

53 responses to this post.

  1. I think AppledocSettings.plist is broken. Could you fix this one, please?

    Reply

  2. Posted by Abhilash Vijayakumar on February 23, 2012 at 2:31 am

    Hi i think this is a good project. Got build errors on Xcode 4.2
    Use of undeclared identifier ‘NSRegularExpression’
    Any suggestion ?

    Reply

  3. Hey, I’m the person behind appledoc, just came accross this post searching for custom build targets :) I find it nice introduction to appledoc and will add it to home page along other external links. Thanks!

    BTW The incompatibility error described above is due to using NSRegularExpression which are 10.7 only. These were introduced with recent contribution that allows better headerdoc integration. It should be fixed by now, update to latest version. The downside is the feature is disabled for 10.6.

    Reply

  4. [...] This post shows you how to set up AppleDoc, and how to integrate with the build process to keep your documentation up-to-date: Documenting you code in Xcode 4 [...]

    Reply

  5. Posted by odpadnem on April 21, 2012 at 11:04 am

    Hi,
    I’m having this error in Xcode 4.3.2 when trying to build:

    ERROR: AppledocException: –project-name argument or global setting is required!

    but, I have those variables set in AppledocSettings.plist. Any idea what causes this error?

    Thanks for any suggestions.

    Reply

  6. Thanks for the article. As a possible improvement, you might want to change the shell script to be:

    appledoc –logformat=xcode $SOURCE_ROOT

    By specifying the Xcode-specific log format, Xcode can show the warnings and errors it discovers when building the documentation in the issue navigator. You can also add that to the AppledocSettings.plist, but I prefer to leave it out so manual command line builds don’t use that style.

    Reply

    • Well, thanks for your comment! It is great to get Xcode showing build issues. Will try this out as soon as I have a chance. Thanks again.

      Reply

  7. Posted by elendil on May 25, 2012 at 11:47 pm

    Following the directions given here, I can get the documentation to show up in the xcode doc browser, but I can’t get it to show anything in the xcode quick help window, which is really annoying.

    I do something along the lines of (foo is a member function)
    /**
    * blah blah blah
    */
    -(void) foo {}

    Should I document in a special way to get the information to the quick help window? I notice that apple content has an “abstraction” field in the quick help window, where most of the text is displayed.

    Reply

  8. Posted by elendil on May 26, 2012 at 4:33 pm

    Still, copying your example doesn’t show anything in the quick help window.

    All it states is:
    “Name: foo:
    Declared in: GraphViewController.mm”

    Reply

    • Let me get back to you. I need to do some research on that.
      In the latest Xcode version 4.3 it really does not work. The documentation gets generated, though. Xcode just does not display it.

      Reply

  9. Posted by elendil on May 27, 2012 at 11:54 am

    Yeah, that’s my understanding as well. I can see it in the documentation browser (is that what it’s called?), but the real (well, the only, actually) reason for me to install and use appledoc (short term, anyway) is to see my documentation in the quick help window.

    Thanks for the help so far. No rush, I have plenty of other stuff to attend to meanwhile.

    Reply

  10. Posted by elendil on May 28, 2012 at 9:07 am

    It wasn’t my intention to belittle appledoc in any way.

    I’ve been using the quick help window a lot to see the contents of structs and such, and it annoyed me that I had to shuffle through my files to read the documentation on my own code.

    I’d rather shuffle through the code than wade through the documentation organizer (thanks), so I really just need the quick help window functionality. For now, that is.

    I’ve always documented and I still do, so it’s not a matter of getting things documented. It’s just a matter of getting the documentation to show when I need it.

    Your question for the google groups words my problem nicely, btw.

    Reply

    • Posted by elendil on May 28, 2012 at 9:07 am

      Oh, and it turns out that I’m a lousy blog user. I keep forgetting to press reply to the post I’m answering, instead of just using the box at the bottom.

      Sorry.

      Reply

      • I solved the issue myself. Just add

        <key>–docset-platform-family</key>
        <string>macosx</string>

        into your AppledocSettings.plist. Xcode 4.3 seems to check this against the platform your code is being developed for.

        Also, I have updated the blog.

    • No problemo :) Let’s see if the autor replies. I’ve been using Quick Help a lot as well so it’s a pity it does not work anymore.

      Reply

  11. Posted by kashif on June 22, 2012 at 3:34 pm

    I have successfully integrate appledoc in my xcode 4.2 . i used following comments:
    /** @name Section title */

    /** Method description */
    – (void)someMethod;

    After succesfully build of my project, i donot see any documentation any where on my macbook :( . I have set company id as com.amathon. I have “/Users/macbook/Library/Developer/Shared/Documentation/DocSets” but there is no filder com.amathon.docs .
    Please help me out.

    Reply

    • In that case you were not successful to integrate it :)

      The result of runnin appledoc in your Xcode project is the docset in the folder you mention in your post. It this was not created, then the build had to fail.

      Did you get any error messages?

      Reply

      • Posted by kashif on June 25, 2012 at 9:54 am

        Thanks for your reply.
        I have not got build errors, and my project got successfully build.

        I have added new aggregate target as ‘Documentation’ and in Documentation shell command i have written “/Applications/appledoc /GIT-Projects/myProject/AppledocSettings.plist /Developer4″ .

        my appledoc executable file is in /usr/bin and also in Applications folder.

        I have copied templates subdirectories in /Library/Application Support/appledoc/Templates

        Please help me out.

      • I am not sure what the /Developer4 folder contains but the syntax shall be similar to this:

        /Applications/appledoc /GIT-Projects/myProject/AppledocSettings.plist /GIT-Projects/myProject/

        Try to run this command in commandline to see what happens. If everything goes well, there is no output but “appledoc version: 2.0.5 (build 789)”. After running the command above you shall have the docset in your ~/Library/Developer/Shared/Documentation/DocSets/ folder.

  12. Posted by kashif on July 3, 2012 at 10:11 am

    I have successfully generated appledocs in xcode 4.2, but i was unable to refresh documentation again. Xcode still show old documentation. I have read from different form to run tell application “xcode” action script but i donot know where i have to place that action script? Do i need to place it just below the “/Applications/appledoc $SOURCE_ROOT/$PROJECT_NAME” ??

    Please help me out.
    Thanks

    Reply

    • The script works in XCode 3 only. It does not work in version 4 anymore. In order to refresh the documentation after it is built you have to restart Xcode.

      Reply

      • Posted by kashif on July 4, 2012 at 9:37 am

        I have restart Xcode even 2,3 times. Actually i have generated documentation with 50 classes in it. Documentation generated very fine. Now i have removed some unused classes and now my classes are 45 in number. Now when i generate documentation then old 5 classes documentation still shows in Xcode 4.2 > Orginizer > Documentation tab.
        I want to remove old documentation of that 5 classes.
        Any other interesting thing is that i have restart Xcode and new documentation has updated documentation in it, but why it show 5 old file documentation as well . :(

      • Sounds to me as a bug in appledoc software. It looks like it does not remove the old files prior generation of the new docset.
        You can file a bug here: https://github.com/tomaz/appledoc/issues

      • Posted by kashif on July 4, 2012 at 9:58 am

        Hmmm, well thanks lobodpav.

      • You are welcome, always glad to help.

  13. I owe you a beer! Thank you!

    Reply

  14. Hi, great post.
    Does this work for iPhone projects?

    Reply

  15. Posted by Theresa on January 25, 2013 at 11:43 pm

    Thanks for this great post!
    One quick question, I set –create-html to be ‘YES’ in the AppledocSettings.plist, but cannot locate the html output. Could you please advise?

    Reply

    • You will find the HTML code in this folder: ~/Library/Developer/Shared/Documentation/DocSets/com.yourCompanySite.YourProjectName/Contents/Resources/Documents/ .

      By the way, –create-html option is set to true by default. You do not need to set it explicitly. It is useful if you want to check your appledoc settings. If you invoke appledoc with –no-create-html, appledoc will validate your settings without generating the HTML output. It is just a time saver – HTML generation takes about 90% of the whole processing time.

      Reply

  16. Posted by Ramani on February 25, 2013 at 2:06 pm

    HI, please specify the path for run script in xcode4.5

    Reply

  17. Posted by Ramani on February 25, 2013 at 2:43 pm

    Please reply soon.

    Reply

    • Posted by Anonymous on February 25, 2013 at 3:38 pm

      Firstly, I have no idea which path do you mean. Do you talk about the location where this tool generates the documentation files?
      Secondly, I will not have time to get into this sooner than during this weekend. Sorry, I am not an official support for the tool ;)

      Reply

  18. Posted by Ramani on February 26, 2013 at 9:44 am

    HI, I am talking about the following script which is not being supported in xcode 4.5 , please help me: /Applications/appledoc “$SOURCE_ROOT/$PROJECT_NAME”

    Reply

    • Posted by Anonymous on February 26, 2013 at 9:46 am

      I see. Let me get into that and come back during this weekend. I am currently snowed under my work issues.

      Reply

    • Just built the latest appledoc version from GIT and tried it in Xcode 4.6. It works perfectly.
      What error message do you get? You need to be more specific so I am able to help.

      Reply

  19. Posted by Kirow on March 10, 2013 at 3:08 pm

    Is it possible to update quick help without restarting Xcode? (using xcode 4.6, quick help do not appear until i restart app)

    Reply

  20. Hello,

    Thank you for posting this. This is very helpful.

    By the way, for those who encountered a problem below, I might have something to help.

    ERROR: AppledocException: –project-name argument or global setting is required!

    —————–

    This problem has something to do with where your AppledocSettings.plist is located and its filename which is case-sensitive. In RunScript -> /Applications/appledoc “$SOURCE_ROOT/$PROJECT_NAME”, it assumes that your AppledocSettings.plist is located within the folder with the name same with your Project Name.

    MyProject/AppledocSettings.plist

    If for any case you added the AppledocSettings.plist inside a folder named “AppleDoc”, your Runsript should now be:

    /Applications/appledoc “$SOURCE_ROOT/$PROJECT_NAME/AppleDoc”

    Hope that helps.

    Thank you again for this wonderful post.

    Reply

  21. This post is extremely useful. Thank you for taking the time to put everything together.

    I have a quick question. Appledoc only documents files located in the same directory as AppledocSettings.plist and its subdirectories. How can I document files located in a different folder? Is there any setting where I can include something like “../MyNewFolder”?

    Thank you in advance for your help

    Reply

    • As per my understanding, the AppledocSessings.plist specifies global options for your project so that you do not have to pass tons of command line arguments to the appledoc script.

      Once having the options file in place, just call appledoc and pass it list of paths you want to generate documentation for. I.e. update your Run Script command in the Documentation target and Bob’s your uncle.

      Updated script from this tutorial: /Applications/appledoc “$SOURCE_ROOT/$PROJECT_NAME” “../MyNewFolder”

      Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 72 other followers

%d bloggers like this: