While developing SimplyStats I had to learn a lot of new stuff, and having integrated help certainly helps in those situations. Apple's Xcode comes with a good set of documentation for all its classes, and can be accessed right from your code. To look up a keyword, just opt-click and you'll get all the information you need (now if somebody integrates StackOverflow.com queries in the IDE he'd be my hero).
Wouldn't it be cool if that was possible for your own static libraries? Well you can! In these days and ages of open source and community development it's not a strange thing that others will use your excellent coding efforts, so providing a descent help set will certainly be appreciated.
The help system for Xcode is called a 'documentation set' (or docset
for short). Constructing a docset manually is a hell of a job. Nobody wants to construct XML files and references by hand. Fortunately there are quite a few (free!) tools that can extract comments from your code and translate them into neat docsets. There's appledoc
just to name a few. I decided to go for appledoc for its simplicity.
In this tutorial i will explain the steps necessary to get your code documentation up and running. This is part 1 about installing appledoc and configuration a build target. In part 2
i will explain more about the options and documentation syntax.
Disclaimer: most of this stuff was scraped together from other sites. If you encounter any problems during installation or use, please refers to the original documentation as I may have slipped on a key somewhere.
This is the easy bit. Open up a command line, navigate to your projects folder and enter the following command to get the latest sources of appledoc
by cloning the git repository (You do have installed git don't you?) :
After the sources are downloaded simply run the install script.
Running this script will compile appledoc and install the resulting executable in your system. You must use sudo
here because there are some permission issues. There are some flags you can change if you like. Check the apple doc readme
Integrating AppleDoc in your build
Now that's all find and dandy, daddy. You got yourself a commandline tool installed, woohoo. Better make it to good use! First let us automate the process of generating the documentation after a build. Although there are several approaches,I will just describe what I did, in order to keep this tutorial quick and easy.
What we are doing in the next steps is:
- Add a build target
- Customize the build phase to call appledoc
- Add a readme file that is used as an introduction page
- Test the build and see if the documentation is generated correctly.
First, we need a new build target name Documentation
. After firing up Xcode and loading your project to be documented, add a new build target. To do this, select your root project
so that the project summary tab appears. On the bottom of the screen you will see an Add Target
button. Click that.
In the dialog that appears, select 'Other' and 'Aggregate'. It doesn't matter if you choose the iOS/Other/Aggregate, or the OS X/Other/Aggregate as they are both basically the same. Anyway, click 'Aggregate' and press Next.
In the product name screen that appears, name your target Documentation or anything you like. I like to use documentation because that's what it does. It's already embedded in the project folder so there's no need to repeat the project name here. After typing the target name, click Finish.
Now we need to customise the target so it'll run appledoc with the proper arguments. First, make sure the Documentation target is selected, and swich to the Build Phases tab like so:
The build phases screen should be empty, except for the Target dependencies section. If it contains other bits, you probably selected the wrong target. Adding a Target Dependency to your library is not necessary. The generation of the documentation does not depend of the code being built because AppleDoc parses your source files directly.
On the build phases tab, click Add Build Phase.
In the little popup that appears, select Add run script:
Below the Target Dependencies phase, a Run Script section is added. Expand the Run Script section to see the details:
In the shell script pane, copy and paste the following command line section (make sure you do not forget the '\' at the end of the line to continue the command):
Note the lines in red. The fist line (--output) is a folder where the generated documentation is placed. This is a temporary location. After appledoc is finished with generating the documentation, the docset will be published to ~/Library/Developer/Shared/Documentation/DocSets anyway, so the location is not really that important. Just make sure that the path exists.
The second red line is a folder structure that gets included in the final documentation. For my project, I used some images. Refer to the Syntax section later on how to include images in your docset.
Next is the creation of a readme.markdown file. Don't worry about the syntax, we'll cover that later in part 2. For now, select your top-level project, and select 'File' -> 'New' ->'File...' and select the Empty document template.
Name the new file readme.markdown. You could name it anything you like, but do remember that this filename is referenced by the script. If you use another name, adjust the script. readme.markdown seems to be the standard naming convention. Also make sure to include the file to the 'Documentation' target, and not to your project.
In the empty file that appears, type some dummy text. We just need to see if it works. You'll get plenty of time after this to write a proper introduction. Perhaps you already had a readme.md file?
Now it's time to run our target to see if the documentation is generated correctly. Switch your target to <your project>/Documentation and hit Run:
After a few seconds (depending on your machine's configuration and the amount of code), you will see a few warnings. The warnings are OK. These are just helper warnings to tell you that some classes or methods are not fully documented. You shouldn't see any errors.
You documentation should have been installed in XCode now. Go to Organizer:
And click Documentation:
Remark: If your documentation doesn't appear right away, this can happen. If your build target ran well, the documentation will be installed. Sometimes it helps to restart Xcode to see the changes in a documentation set. This is also the case for quick-help documentation (more about that in part 2), which also doesn't refresh until you restart Xcode. This is a bug in Xcode 4.6.3, and will probably be fixed in Xcode 5.
And there you have it!! Your own integrated help. But don't think you are done, you have got a lot of typing to do. This is covered in the next part where I'll discuss the syntax to document your code.
Meanwhile, to get you started, you should decorate all your interfaces with at least a small description like so:
For details on how to document your code, check out part 2
of this tutorial where I show some of the syntax. I hope you found this useful and if you have any questions or suggestions, do not hesitate to use the comments below or send me a note using thecontact page.