Our DNA is written in Swift

Amazing Apple-like Documentation

I know I know, Documentation is a bad bad word, especially for us creative people. The true creativity is in writing code, not in writing comments, isn’t it?

Well, regardless, you might find yourself in the situation that you want other people to reuse your code. Or better yet, a different self of you in a year should be able to understand your line of reasoning of today. If you do programming for a longer time you will pass the phase of being shocked at how bad your code was and then get into the phase of having no idea what you where thinking. So a liberal sprinkling of comments can help you get up to speed on your old code.

I invented a technique of chewing on a portion of a programming puzzle where you comment almost every line of code as if you were to explain to somebody the steps in your ingenious approach. Maybe somebody else coined a term for this, for me it helps me sort my thoughts. And probably will do the same a year or ten from now. So commenting comes naturally to me, Documentation by Comment-ation is a logical extension to the concept.

Apple has nicely written documentation for their APIs though their process of creating it is hard to duplicate for us solo or small team developers. Apple has an entire department that writes the documentation the “Apple Developer Publications Department”, googling for them you can even find a two-year-old style guide for writers. Just consider this quote from it on page 6 just to see how much over our heads this “proper documenting” is:

“In general, follow the style and usage rules in:

  • The American Heritage Dictionary
  • The Chicago Manual of Style
  • Words into Type

Exceptions to certain guidelines in these resources are noted in this guide.
In cases where reference sources conflict with each other, follow:

  • The Chicago Manual of Style for questions of style and usage
  • The American Heritage Dictionary for questions of spelling

Also refer to any department-specific materials provided by your editor.”

No way I’m going to start perusing a dictionary for my comments! And I guess neither will you…

Apple apparently is using the RenderX XEP engine to convert their own XML documentation to the nice PDF and HTML output you see online today. That’s the second reason why their process is out of reach for us.

Enter AppleDoc

One-person company Gentle Bytes saw our need for a simple and usable way to generate nice-to-look-at documentation from source code comments. So he started the AppleDoc open-source project in or around April 2009. It’s grown over 2 years and in January 2011 the version got bumped to 2.0. This is finally a full rewrite that no longer depends on Doxygen to parse the source code.

AppleDoc works such that it parses your source code and assembles the source comments in a structure strikingly similar to what we are used to from Apple. There is documentation as to how to construct your comments but I found it not very intuitive. So let me give you an overview and tutorial here as to what I learned to help you get up to speed as quickly as possible on using AppleDoc yourself.


You need to clone the AppleDoc Xcode project from github and build the command line tool. I assume that you have previously set up github on your development machine.

git clone git://
cd appledoc
open appledoc.xcodeproj

In Xcode switch to the appledoc target and build it. You will see the appledoc entry in the Products group turn black.

Copy the appledoc command line utility to any folder in your path, I put it in /usr/local/bin. This way it is available regardless of what your current working directory is. To see that this is working and to see the appledoc help you can do “appledoc –help”.

Commenting Correctly

AppleDoc requires that you adhere to a certain style of commenting that is slightly different from the standard C comments you are used to, namely /* comment */ and // single line.

Classes and Categories

For every class or category that you are documenting, add one or more paragraphs of comments describing what the class is used for. This goes between the imports and the interface in the header file.

/** This class demonstrates AppleDoc.
 A second paragraph comes after an empty line.
	int i=0;
 And some sample code can also be in a block, but indented with a TAB.

Note the second asterisk on the opening of the comment. Paragraphs are separated by an empty line. All this text is parsed as markdown syntax, the inventor Gruber has an introduction. You can have sample code in the text as well, in it’s own block and indented with a tabulator. The above turns into a nicely formatted Overview section.


AppleDoc automatically turns anything looking like an Objective-C method into a cross-reference. That’s usually what we want, but will get you some warnings if you reference external classes in a sample block. See below how you can solve that.


The comment block before a  method (again in header) will be turned into the description 0f the method. The default behavior is to use the first paragraph for the short description and all paragraphs for the “Discussion”. I disabled this repeating of the first paragraph because I find that it looks weird to have the same text twice, not like Apple.

 * @name A name under which this method appears under "Tasks"
 *  ---------------------------------------------------------------------------------------
/** This is the first super-awesome method.
 You can also add lists, but have to keep an empty line between these blocks.
 - One
 - Two
 - Three
 @param string A parameter that is passed in.
 @return Whatever it returns.
- (NSString *)someMethodWithString:(NSString *)string;

The comment block with the @name serves for the grouping of methods in the “Tasks” section at the beginning of the page for the class/category. You should group similar methods under one such section, you don’t have to repeat it because the @name is good until the next one. You see that you can also have lists (numbered or not). You need an @param for each parameter of the method. If it has a non-void return value then you also need an @return to describe that. Omitting any of these will get you a warning.

You see that the first paragraph of the description ended up at the top, the rest of it including the list went to the Discussion part.

Some more bells and whistles are possible, shown here:

/** This is the second super-awesome method.
 Note that there are additional cool things here, like [direct hyperlinks](
 @param number A parameter that is passed in, almost as cool as someMethodWithString:
 @return Whatever it returns.
 @see someMethodWithString:
 @warning *Warning:* A blue background.
 @bug *Bug:* A yellow background.
- (NSString *)someMethodWithInteger:(NSInteger)number;

This shows cross references inline and via the @see tag. For external hyperlinks you put the link words in square brackets, the link itself in round ones. Finally you have a choice of blue or yellow box for warnings/notices.

Unfortunately there is no support for constants, enums and other things you might want to put in your headers, but it’s being worked on as we speak. For now you should probably put the possible values for an typedef’d enum in a simple list.

Building the Docset and HTML

Once you have added sufficient commentary as outline above you will want to build the documentation. AppleDoc primarily builds docsets which are essentially bundles with a bunch of HTML and xml index files. These docsets integrate with your Xcode for easy browsing and searching.

It took me quite a bit of tweaking until I got the parameters right to get the output I wanted. Also there are apparently some bugs that manifest themselves if you have some switches in the wrong oder. For quick building I set up a Documentation target where I added a “Run Script” build phase to execute this script. This would just as well work in a separate shell script, though you’d have to substitute the actual path for the PROJECT_DIR.

/usr/local/bin/appledoc \
--project-name "DTFoundation" \
--project-company "Cocoanetics" \
--company-id "com.cocoanetics" \
--docset-atom-filename "DTFoundation.atom" \
--docset-feed-url "" \
--docset-package-url "" \
--docset-fallback-url "" \
--output "~/help" \
--publish-docset \
--logformat xcode \
--keep-undocumented-objects \
--keep-undocumented-members \
--keep-intermediate-files \
--no-repeat-first-par \
--no-warn-invalid-crossref \
--ignore "*.m" \
--ignore "LoadableCategory.h" \
--index-desc "${PROJECT_DIR}/readme.markdown" \

Here are my reasons for the various switches:

  • project-name, project-company and company_id are standard
  • the atom filename and the urls are necessary to let the docset know where it can get an update
  • the output directory should be a place outside of your Xcode project. I found that having the generated documentation inside a github project does not make sense.
  • publish-docset causes AppleDoc to generate the Atom feed and xar archive file
  • logformat-xcode makes the output compatible with Xcode so that you get inline warnings
  • keep-intermediate-files is necessary to preserve the original HTML output which you can put on your server for online reading
  • no-repeate-first-par is the setting that does not duplicate the first paragraph into the discussion section
  • no-warn-invalid-crossref omits the annoying warnings that you get when AppleDoc cannot find a reference to class or method
  • we’re ignoring the .m files because otherwise AppleDoc would also try to get comments from these. We only want the comments from headers used also we don’t want the documentation say that a method was defined in the .h and the .m files which is unlike Apple.
  • the LoadableCategory.h is another file we explicitly need to ignore, it is a dummy class that forces the linker to also load certain tagged categories. No use having that in the documentation.
  • the index-desc is the path to a markdown file which additionally gets injected into the index page

The last switch is of special interest. Without it the index page of the docset is relatively barren. But since all of AppleDoc is based on markdown you can also re-purpose the readme file you usually have in the project root of your project as an introduction to the project. Write once, reuse: I’m loving it!


AppleDoc will also install a generated docset into the same location where Apple’s docsets are residing. You can see these and install new ones via Xcode preferences, Downloads, Documentation tab.

You can add docsets on this screen via the plus button and by specifying the URL of the Atom feed. Remember, AppleDoc can generate this feed for you. If you leave the generated output in the publish folder around and update the project version then AppleDoc will add the new version to the feed file. So all you need is to copy the xar and the atom files to your web server after making sure that you specified the URLs correctly. This way somebody only needs to have the URL of the atom feed to install the docset.

The contents of the html folder in your output directory contain a full HTML site for the entire documentation. You can upload that to your web site as well, it is essentially the same content as in the docset. If you do, then people can browse the documentation outside of Xcode and you can also specify the URL there as fallback URL in your docset.

GitHub has a mechanism called GitHub Pages which you can enable via the admin area of every project. Once enabled you can put the web server files into a gh-pages branch of your open-source project. I finally got it working as well, but it is a bit weird having to constantly move around between the master and the gh-pages branch.


By adopting the described style of commenting methods and classes/categories you immediately reap the benefit of being able to generate beautiful docsets and HTML documentation. You can also inject your additional markdown files to enhance the index or even going as far as adding custom images and full HTML files. Development on AppleDoc continues – although slowly – and we’re looking forward to getting support for other things we’d like to document: notifications, protocols, enums and constants.

The main advantage of AppleDoc is that the comments also enhance your source code, so that even people without Xcode can read what you wrote. This way other developers benefit because they can look up your methods and see what your thoughts where. Often the availability of documentation is what many people use to decide whether or not they should add a dependency on your library or framework.

Finally it is yourself who will benefit in the long run because your commentary will allow you to understand what you where thinking many years ago. Don’t discount this possibility, we all get older all the time.

Categories: Apple


  1. WOW! This is exactly what I was looking for! Thanks a lot!

  2. Is there anyway with appledocs to get those nice bubbles that appear in XCode when you press “Opt + Click” in a class name or variable?

  3. This is very good, however I’m looking for stylesheet which transform XML document into something like apple genrated PDF . Any hint ?

  4. Hi. I also like Apple Documentation’s style a lot! But my main target is not to have automatic documentation from code, but rather be able to write documents in Apple’s style with little effort…
    I managed to make a pixel-by-pixel clone of such style for Apple Pages, but it doesn’t include automatic header and footer, or references (by the way, the main font they use looks like the commercial Myriad Pro that comes with many Adobe products, with a slightly narrowed kern).
    It would be great to have a LaTeX documentclass to achieve such results! I’m a LaTeX user, but I’m definitely not able to create a document class myself. I’ve also looked for something like this on the Internet, but it looks like nobody’s working on this.
    Any idea coming from your experience on the similar, but harder, work you mentioned in this post?

  5. you get these bubbles for free if you install a DocSet.

  6. Thanks, good to know 🙂

  7. I’m getting following attributes in documentation:

    I need to add fourth one named “Example” there.

    Please help me

  8. The BIGGEST problem with Appledoc is that it is not a BSD license.

    If you read it closely they require you to attribute the fact that you used Appledoc to create the documentation. This is akin to Microsoft requiring that you attribute the fact you used word to write a letter.

    Worse, their license ALSO says that you can’t use their name (including Appledoc) to advertise. However, the attribution IS advertisement (there is no other reason for it than to advertise that you used Appledoc). Hence their own license violates itself.

    GCC does not require me to say “yo, I used GCC to compile code” – I see no reason Appledoc should require me to do the same. If they help me write the documentation, then they get an attribution – formatting MY words isn’t going to cut it.

  9. I think you are misreading/misunderstanding the (modified) BSD license that is attached to AppleDoc itself: (bottom).

    This license primarily covers the SOURCE CODE of AppleDoc, but not output generated with it as a normal BSD license would.

    There is one extra line covering output: “Redistributions of documentation generated by appledoc must include attribution to appledoc, either in documentation itself or other appropriate media.”

    This happens automatically by AppleDoc adding a “Generated by AppleDoc” at the very bottom of each page, see for example

    This basically means that you have to accept this “Generated by” line and may not remove it, but that’s a small price to pay IMHO for a free tool. The other three items from the BSD license mean that if you compile your own AppleDoc derivative then you have to state that you based it on AppleDoc and cannot claim that AppleDoc thinks your app is great. These don’t have anything to do with generated documentation.

  10. I keep getting this error when I use drops script from the command line: ${PROJECT_DIR}/readme.markdown: bad substitution. Where PROJECT_DIR is replaced with . so it can find my project in the current directory. Any one know why?

  11. Great introduction, really easy to follow!

  12. its amazing man…great. Thank you.

  13. Hi,

    Thank for the wonderful description of the product. I tried it out and I was able to add the documentation successfully.
    But I have an issue, the parameters and return value don’t show up in the quick help (Alt+click on a method name)
    They are displayed in the documentation part of the organizer, but it would be better if they appear in quick help too.


  14. Taxis in all London airports offer round-the-clock service, confirming you
    a trouble-free journey. Enterprise also informed us that
    they will pick up passengers after the cruise if they
    want to rent a car to spend time visiting around Manhattan before their flight home.

    There are many airport ways for your airport transfers like shuttle transfers,
    airport transfer, shuttle transfer, airport minibus,
    holiday transfers, group transfers, holiday taxis etc.

  15. It is much easier to compare different web design service by reading online reviews.
    Like everything in business is important, getting a website is important too.

    There are lots of commercial templates available, and frankly,
    they are beautiful, but I am going to give you some hints
    on where to find free web templates.

  16. Is there any way to alphabetically sort the functions in the doc.

  17. It is important to know what you are paying for comes up to
    your standards prom limousine service. Walk out to the elevator
    and then clean up the mess to keep your cover. The ‘Best of Orange County’ is in a sense, a walking or, rather, delivered billboard.

  18. h proper dose cialis 20mg