How to Generate Beautiful Apple-Style Documentation in Xcode 5

Good code should be self-documenting, but sometimes you also need to generate external documentation for reference purposes. In this post I’ll show you how to use two open-source tools and a build script to create beautiful, Apple-style HTML documentation files in Xcode. I’ll also show you how to create docsets for Xcode so that your class references show up right along side Apple’s! It will be a seamless and dare I say, enjoyable, process for generating documentation.

Installing the Annotation Plugin

First install a fantastic open-source Xcode plugin called VVDocumenter-Xcode that makes annotating your source code a breeze! Open a Terminal window and clone the following repository:

git clone https://github.com/onevcat/VVDocumenter-Xcode.git

Note: this is for Xcode 5 only. For Xcode 4, use:

git clone https://github.com/onevcat/VVDocumenter-Xcode/tree/Xcode4

Open the VVDocumenter-Xcode.xcodeproj file inside the VVDocumenter-Xcode folder your just created. Press Build. That’s it! You’ve just installed the plugin. Now restart Xcode, open one of your projects, and above any method in your code type three slashes:

///
-(id)initWithFrame:(CGRect)frame
...

.NET developers will recognize this gesture from Visual Studio! The plugin will instantly insert an Xcode-style snippet pre-filled with all the right placeholders for your method, including description, parameters, and return type! Press the tab key to move through each of them one by one. It is a thing of beauty!

vvdocumenter

Installing the Documentation Generator

Now let’s setup a second tool called appledoc to actually generate real documentation files from your annotations. Unfortunately, the project currently does not build, but you can download the binary here.  Extract the zip file and copy the appledoc executable inside into the following folder:

/usr/local/bin

Test your installation by typing this in an Terminal window:

which appledoc

This will show you the location of the appledoc binary. If you don’t see such a message, something went wrong; try again.

Configuring the Build Script

Now let’s create a build script in Xcode to automatically invoke appledoc every time that we do a build. Click on your Project name in the Navigator, and then click on your main build target under Targets. Click on the Build Phases tab. Go to Editor > Add Build Phase > Add Run Script Build Phase. Copy and paste the following code over the text that says ‘Type a script or drag a script file from your workspace to insert its path.’ Remember to update your name and company name!

#if [ ${CONFIGURATION} == "Release" ]; then
APPLEDOC_PATH=`which appledoc`
if [ $APPLEDOC_PATH ]; then
$APPLEDOC_PATH \
--project-name ${PRODUCT_NAME} \
--project-company "Your Name" \
--company-id "com.yourcompany" \
--output ${PRODUCT_NAME}Docs \
--keep-undocumented-objects \
--keep-undocumented-members \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--exit-threshold 2 \
${PROJECT_DIR}/${PRODUCT_NAME}
fi;
#fi;

Your documentation will be generated in a folder called ${PRODUCT_NAME}Docs under your project folder. This folder will not be tracked by git unless you explicitly use the git add command. It’s up to you whether you want documentation in your repository or not. You can also modify the script to save the documentation in a folder outside of your repository. For more options visit the appledoc site.

Testing

Try it out! In your Issue Navigator and you will see tons of warnings about missing documentation. Use that to help you find places where your documentation annotations are missing. If you want the script to run only on release builds, just remove the hash symbol from the first and last lines of the build script.

Now open your project folder in Finder and you should see a new ${PRODUCT_NAME}Docs folder! Inside there is an html folder. Open the index.html file in a browser and let the oohs and aahs begin! Inside your docs folder you should also see a docset folder. Inside you should see a docset-installed.txt file telling you that your docset was installed to Xcode, and where it is located. By default, docsets are located here:

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

Now your class references are now available side-by-side with Apple’s own documentation inside Xcode! How cool is that? You can see them by going to Help > Documentation and API Reference.

And there you have it! With better documentation you make your co-workers, clients, and even your future self much happier! Happy coding!

About these ads

About Martin Rybak

I am a New York area software developer and MBA with 10+ years of experience on the Microsoft stack. Over the past few years I have also expanded into iOS development using native Objective-C. I architect and develop full-stack web applications, iOS apps, database systems, and backend services.

21 responses to “How to Generate Beautiful Apple-Style Documentation in Xcode 5

  1. michaelrcampbell

    Thanks for that Martin. This was extremely helpful!

  2. Great to see a detail tutorial of doc generation and an introduction of VVDocumenter here. Thank you, it is helpful!

  3. Getting error : ERROR: AppledocException: No predefined templates path exists and no template path specified from command line!

  4. Hey..its working now. thanks a lot.. it is a great blog and great effort for solving my issue..

    i don’t know i follow the steps given in https://github.com/tomaz/appledoc and try
    sudo sh install-appledoc.sh (if you need templates add ‘-t default’)

    sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

    and set my edit scheme to debug for all.. archive..build and all things and its working fine.

    Thanks again.. Happy Coding:)

  5. Great post. Most helpful thing I found over the internet for generating doucments

  6. Ram

    Good evening Martin,

    Thanks to help for sql connection. Now I am creating documentation of my source code. My client want documentation for both header file as well as implementation file. But your way create doc for .h file only. So please let me know any correction to create doc for .m file also.

  7. The appledoc doesn’t work on Xcode 5.1. So I had to install it from the binary files provided by the creator from this link https://github.com/tomaz/appledoc/releases/tag/v2.2-963

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.

%d bloggers like this: