Show Menu

Looking to hire an app developer?

Submit your 30 day Job Listing for FREE

iOS development tutorial

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 5.

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!


Installing the Documentation Generator

Now let’s setup a second tool called appledoc to actually generate real documentation files from your annotations. Fire up Terminal and clone the following git repository:


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

Build the project by running the following build script. Enter your password when prompted.


cd appledoc
sudo sh ./install-appledoc.sh -b /usr/bin

You should see a cheerful install succeeded message. 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 release 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-install-docset \
--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 file. To install it in Xcode, or to distribute it to other Xcode users, simply copy it into this folder:


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

Note: you can also have appledocs automatically install the docset every time you build by removing the –no-install-docset flag in your build script.

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!

having issues?

We have a Questions and Answer section where you can ask your iOS Development questions to thousands of iOS Developers.

Ask Question

FREE Download!

Get your FREE Swift 2 Cheat Sheet and quick reference guide PDF download when you sign up to SwiftMonthly


Sharing is caring

If you enjoyed this tutorial, please help us and others by sharing using one of the social media buttons below.


Written by:

Martin is a New York area software developer and MBA with 10+ years of experience on the Microsoft stack. Over the past few years he has also expanded into iOS development using native Objective-C. he architects and develops full-stack web applications, iOS apps, database systems, and backend services.

Comments

comments