Adding Documentation – appledoc

Yes, there have been thousands of posts on this topic. I guess this is more a reference for me, but perhaps it will be useful to you too. That said, this is for Xcode 4.x and Xcode 5 is coming out soon… <sigh>

  • Clone the appledoc repo at:  https://github.com/tomaz/appledoc.git
  • Build the project.  After it completes, in the project navigator, open the Products folder and right-click on appledoc, and Show In Finder.  Copy that file to your /usr/bin folder. (There is some discussion over which folder, read here.  Ultimately it ‘just works’ in /usr/bin)  Do this every time you update the appledoc project.

Documentation is generated in your project by creating a target designed to do this task.

  • Click on your project name at the top of the Project Navigator in Xcode, and you should see the settings screen in the main panel.  Add a Target, of type Aggregate.  Call it Documentation.
  • This target basically needs to do one thing: Run a Script.  So, add a build Phase of type Run Script.  We will come back to this later.

Appledoc can be run completely from a script with command line args, but let’s use a .plist to specify our parameters.  Create a file called AppledocSettings.plist, put it in a folder (relative to your project root) called ‘appledoc’ and copy-paste this into it:

<?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.YOUR_COMPANY_NAME</string>
	<key>--create-docset</key>
	<true/>
	<key>--create-html</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>iphoneos</string>
	<key>--output</key>
	<string>appledoc</string>
	<key>--project-company</key>
	<string>YOUR_COMPANY_NAME</string>
	<key>--project-name</key>
	<string>YOUR_PROJECT_NAME</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>
  • So now that you’ve created that, import it into your Xcode project for easy editing. Don’t add it to any target because it’s just to be visible to us in Xcode, not packaged in any bundle.

You should read up on what the different parameters do, and you can add further parameters that you need by running appledoc –help from the terminal.  Hopefully you should see how these command line args translate to this .plist file.

Go back to the Documentation Target Settings, and now we will provide the script for it to run:

appledoc \
"${PROJECT_DIR}/appledoc/AppledocSettings.plist" \
"${PROJECT_DIR}/PathToSourceFiles"

NOTE: “PathToSourceFiles” is really the path to where you have the source with the documentation you want to have generated.  So this will be specific to your Codebase.

What just happened?  We told appledoc to run with the settings provided in the .plist, and generate documentation for any source located in PathToSourceFiles.  Note in the .plist file above I have the argument “ignore .m” set to YES, since this is private.  If you’ve done your job right (see my posts on the importance of Encapsulation!!) you won’t need to document this source – your comments should hopefully be enough.

  • Build the Documentation target, you’ll see in the Xcode Organizer that your source has been added to the Xcode documentation library.  Awesome!

Actually Writing Documentation

There are two things that will help you writing Documentation formatted correctly for appledoc.  Oliver Drobnik over at Cocoanetics provides an excellent tutorial on this.  (Search for Commenting Correctly).

Using those examples, I would also recommend you create some Code Snippets for Xcode so that you can easily just drop in a template to document a method or a property or whatever.  Here is a link for setting up documentation Code Snippets in Xcode.  With the examples at Cocoanetics, you could create a few snippets for different situations (Method, Property, Class Description, etc) in no time!

I also suggest looking at the AFNetworking Docset in Xcode, and if you want your documentation to look like theirs, just go to that relevant source file to see how they formatted it. AFNetworking is really well documented!

Deleting Docsets

If you look in the appledoc folder where I asked you to place your AppledocSettings.plist, whenever your Documentation is generated, appledoc places a file there telling you where it placed the docset.  You can navigate there and delete any docsets you don’t want to appear in Xcode anymore.  Restart Xcode and this will be up-to-date!

Happy Coding!

UPDATE: Just added some code you can copy-paste to make your own Code Snippets in Xcode. See my github page for that

About these ads

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