appledoc docs examples xcode

Xcode integration

You can setup Xcode to handle automatic source code documentation generation for your project. Just add a build script and run appledoc using your desired command line. You can either have it run each time you build or add the script to a separate target to run it manually. The later is especially useful for larger projects which may take significant overhead having run appledoc each time you compile your binary.

Appledoc can help you integrate source code issues into Xcode by telling Xcode which files and lines have issues like undocumented objects or invalid cross references. It also can tell Xcode whether documentation generation has been succesful or not.

Xcode compatible log format

Appledoc allows you choosing between various output log formats through --logformat cmd line switch. These result in more or less verbose formatting for each log message. But there is special log format suited for Xcode builds:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--logformat xcode
.

This example builds on minumum command line, changing log format to xcode. If you're running appledoc as Xcode build script, you're encouraged to use this format. It'll format warnings and errors in the way Xcode will be able catching them and displaying them within build results. Even more, clicking them will navigate you straight to the offending line!

Implementation detail: With some log formats, appledoc will emit the source code file name and line number inside which the log message call is located. This is appledoc's own source information, primarily useful for debugging purposes - pinpointing the source code in case of troubles. However this renders no useful information of which of your source files has undocumented entity for example. Therefore --logformat xcode uses context aware log formats where applicable. It tells Xcode which of YOUR source files (the files appledoc is actually parsing over) contains an issue and which line the issue is in. Not something you have to be aware of, it should be intuitive by itself, just wrote it here for those that may get confused between the two...

Controlling appledoc build results

Appledoc returns integer value indicating the overall generation result. If everything was fine, 0 is returned, otherwise a positive value. The greater the value, more serious the error. By default appledoc returns the following exit codes:

• 0: Success!
• 1: At least one warning was logged.
• 2: At least one error was logged.
• 3: At least one fatal error was logged.
• 250: Unhandled exception (Oops message).

This may be fine if you treat documentation warnings seriously. However, although warnings indicate there are some issues in your source code comments, this doesn't actually prevent appledoc generating usable documentation, therefore you might want to tell Xcode documentation was generated anyway. appledoc allows you specify exit code threshold below which 0 is returned regardless of the actual result:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--exit-threshold 2
.

This will tell appledoc to only return non zero if indicated return code is 2 or greater, reporting success for all lower exit codes. This effectively returns success in case warnings were logged. Similarly, you could suppress more serious errors, although that is not recommended.

Note: Due to the way exit threshold values are used, values smaller than 2 don't affect reported result.