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!
--logformat xcodeuses 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.