Objective-c code Apple style documentation set generator.
IMPORTANT NOTICE: collaborators needed
appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set. Although there are several tools that can create HTML documentation for Objective-C, all of those known to me fall short in meeting the minimum of goals described below.
Main goals of appledoc:
To make your experience with appledoc as smooth as possible, we warmly suggest reading this whole document as well as all online documentation mentioned in "using appledoc" section below!
Usage of appledoc is allowed under the terms listed in LICENSE section at the bottom of this file!
Want to keep updated? Follow us on Twitter - @gentlebytes.
The recommended way is to clone GitHub project and compile the tool from Xcode. As cloning GitHub project will create the link to the main repository, it greatly simplifies future upgrading too. To install, type the following in the Terminal:
git clone git://github.com/tomaz/appledoc.git
This creates appledoc directory. Within you can find appledoc.xcworkspace Xcode workspace; open it and compile appledoc target - this should work out of the box, however your system must meet minimum system requirements, see below. I recommend you copy resulting appledoc executable from build directory to one of the directories in your path (
echo $PATH) to make it easily accessible.
Optional: Appledoc is selfcontained and contains the necessary template files. IF you want to modify these default from Templates subdirectory to one of the expected locations:
You can also use install-appledoc.sh script to perform quick installation. Open Terminal and switch to appledoc directory. Type following command:
sudo sh install-appledoc.sh (if you need templates add '-t default')
It compiles appledoc and installs its binary to /usr/local/bin and templates (if wanted) to ~/.appledoc by default. You can override this directories with -b and -t options respectively. For example:
sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc
Alternatively with Homebrew:
brew install appledoc
Homebrew does not install templates by default.
appledoc --helpto see the list of all command line switches. Read more about appledoc on appledoc site. Also read wiki pages for some more in-depth articles.
Use appledoc Google group as a forum for questions on usage or other general questions.
Use appledoc issues page to submit bug and feature requests. Before submitting new issues, check the forums to see if your question is answered there - unless you can confirm your issue as a new feature request or a bug, you should start at the forum to keep GitHub issues clean. Also read through issues to see if the issue is already there and vote on it or add a comment (don't forget about closed issues).
To keep up to date, just go to Terminal and cd into appledoc directory, issue
git pulland recompile appledoc.xcodeproj. Don't forget to overwrite appledoc executable you've copied to $PATH :)
If you also want to compile and run AppledocTests (unit tests) target, you need to copy all the frameworks indicated within Libraries & Frameworks group to shared frameworks directory before building unit tests target! This is not required for building the appledoc tool itself.
You can setup Xcode to automate appledoc document creation. Find out how using a Run Script and your project's Build Phases.
Pre-generated documentation and docsets for most Cocoa frameworks are available at:
Have problems? This is what you can do to troubleshoot:
git pulland run with latest version again.
--verbosecommand line switch. Default level is 2, but you can progressively increment verbosity up to 6 with each level giving you more detailed information. As this will give you a lot more information, you may want to concentrate only on specific set of source files you have problem with. Note that increasing verbosity will result in slower performance so using levels above 4 for every day use is not recommended.
If you wish to contribute, see the Developer Notes file for short overview of how appledoc works internally.
appledoc is licensed with modified BSD license. In plain language: you're allowed to do whatever you wish with the code, modify, redistribute, embed in your products (free or commercial), but you must include copyright, terms of usage and disclaimer as stated in the license, the same way as any other BSD licensed code. You can of course use documentation generated by appledoc for your products (free or commercial), but you must attribute appledoc either in documentation itself or other appropriate place such as your website.
If for whatever reason you cannot agree to these terms, contact us through contact form on our about page, we'll do our best to help you out you out and find a workable solution!
Copyright (c) 2009-2011, Gentle Bytes All rights reserved.
Redistribution and use in source, binary forms and generated documentation, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Redistributions of documentation generated by appledoc must include attribution to appledoc, either in documentation itself or other appropriate media.
Neither the name of the appledoc, Gentle Bytes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Gentle Bytes [email protected]