appledoc docs examples advanced

Advanced command line examples

Prepare documentation set for publishing

Appledoc can prepare documentation set for publishing too, just add --publish-docset, --docset-feed-url and --docset-package-url switches to command line like this:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/Projects/Help/appledoc
--docset-feed-url http://gentlebytes.com/downloads/%DOCSETATOMFILENAME
--docset-package-url http://gentlebytes.com/downloads/%DOCSETPACKAGEFILENAME
--publish-docset 
.

This command line will create and install documentation set and finally run docsetutil over installed docset to create compressed documentation set file and atom feed you can upload to your server. Both files are saved to publish subdirectory within --output path. You can then pass them to rsync or similar tool for actually uploading to your server (although command line switch may suggest so, appledoc doesn't do uploading itself, it only generates necessary files!). When uploading, make sure the files are available at the URLs given to --docset-feed-url and --docset-package-url! You can use --print-settings command line switch to have appledoc print the actual URLs after replacing template placeholders.

Important: When you increment versions, the atom file needs to be updated properly - a new entry needs to be inserted for each new version. To allow that, appledoc checks if the atom file already exists at output path. If so, the existing file is updated with new information by docsetutil. First the file is parsed and if an entry is found corresponding to --project-version, the entry is updated. If no entry matching the version is found, a new entry is added to the file. Therefore it is important to keep the generated atom file at output path (you can safely remove package (.xar file) after uploading though)! In fact, this is the mechanism used by appledoc to have the atom file updated with new versions, so keep that in mind!

Note: Notice the usage of %DOCSETATOMFILENAME and %DOCSETPACKAGEFILENAME placeholders for command line switches - it is [recommended to use these]({{ pcurl('appledoc-docs-settings#placeholders') }}) to keep the actual filenames in sync with information written to atom file!

Note: You can also include --docset-fallback-url so that Xcode can get to your documentation installed on remote server. The location given should point to the contents of your DocSet Documents folder (at present appledoc doesn't prepare a copy of this folder, you can find it either at --docset-install-path (if you use default value, add [--print-settings]({{ pcurl('appledoc-docs-settings#example-print-settings') }}) command line switch to have it printed for you) or alternatively use --keep-intermediate-files and find the files at your --output location).

Important: If Xcode gives you package not found error when accessing published documentation set, and you are sure the files are on required location, check your web server mime type settings and add settings for xar files if not found. You can verify this by pointing your browser to the location of your xar file - it will give you 404 error if mime settings are not correct.

Undocumented objects and members handling

By default appledoc ignores all undocumented classes, categories, protocols as well as methods and properties. However you can instruct it to include undocumented objects and members in generated HTML:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/Projects/Help/appledoc
--keep-undocumented-objects
--keep-undocumented-members
--search-undocumented-doc
.

This command line would include every parsed object (class, category and protocol) and it's member (method or property). Additionally it would search for documentation of undocumented members in super classes and adopted protocols. To better understand how these switches interact with each other this is the workflow used:

• If --search-undocumented-doc is enabled, all undocumented methods and properties documentation is searched for in known super class hierarchy. If documentation is found in any of the super classes, it is copied to inherited member as well. If documentation is not found in superclasses, it is searched for in adopted protocols and copied from there if possible. If option is disabled, members are left undocumented and are handled that way as described below. This option is enabled by default (in fact above example doesn't need to enable it explicitly); to disable, use --no-search-undocumented-doc.
• If --keep-undocumented-members is enabled, all undocumented methods and properties are left and used for output. If disabled, any undocumented method or property is removed from class (of course any documentation copied over from super classes or adopted protocols in previous step is considered valid too). This option is disabled by default.
• If --keep-undocumented-objects is enabled, all undocumented classes, categories and protocols are left. If disabled, all undocumented objects that have no documented method or property are also removed. However if undocumented object contains documented members, the object is left and used for output regardless of this option (overview section would be ommited in generated HTML in this case)! This option is disabled by default.

Merging category documentation

Apple seems to merge categories documentation to it's class to keep it together and appledoc is configured to do the same:

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

This command line will merge categories and extension documentation to their classes as long as the class is also found in the given source files. In fact, this behavior is enabled by default, so you can skip --merge-categories switch in the above example and get the same result. You can refine how categories are merged with two additional switches:

• --keep-merged-sections: If enabled, all @name sections from categories are preserved, otherwise all methods from category are merged into a single section using category name as section title. This is disabled by default as this seems to be how Apple does it. Enabling this option may result in fragmented class documentation, so experiment a bit to see what works best for you.
• --prefix-merged-sections: If enabled, all merged category section titles are prefixed with category name, otherwise original title is left. This is disabled by default, but you can enable it if it suits you better - again, experiment to see what works for you. This switch is ignored unless --keep-merged-section is enabled! Important: extension sections are never prefixed regardless of this setting!

Both switches are ignored if categories merging is disabled (i.e. --no-merge-categories!

Controlling cross references detection

By default any valid cross reference word or URL, optionally embedded within <> markers is converted to cross reference link in resulting documentation. Although this greatly simplifies cross references handling, it may lead to unexpected links. For example if one of your methods or properties is called paragraph, every word paragraph is converted to cross reference to that method. To give you control over which word should be converted to cross reference and which shouldn't, appledoc gives you two options: turning on explicit cross references or specifying custom cross reference detection markers. Let's look at both of them:

Explicit cross references detection

This is simpler of both. It's enabled with:

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

This command line will check cross references only in words embedded with <> markers. This gives you control over which word should be converted to cross references and which not, but requires you to use additional syntax; above example would need to be written as <paragraph>. Note: without explicit cross references option, you can still embed words with <> markers - this is optional by default, but with explicit option, markers are required!

Custom cross references markers

If you don't like default markers, you can use arbitrary ones for embedding cross references in your code. This is great for porting your code from other documenting systems. Here's an example:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--crossref-format "#%@#"
.

This example would only check for cross references embedded within ## markers, for example #paragraph#. Even more, --crossref-format takes regex expression, so you can become very creative. For example, to change markers to # and make them optional, you'd use --crossref-format "#?%@#?" instead. Make sure you don't forget to include %@ placeholder - this is replaced with actual cross reference matching regexes for various types of links!

Important: Take care when specifying custom markers - make sure you don't use one of the formatting markers (*, _ and similar); although appledoc will not warn you about it, results are unpredictable and either cross reference or format will not be recognized. Also make sure to not use capturing parenthesis (this is especially important for starting marker)! Cross references matching relies on exact capture group numbers for finding specific parts of reference (like object and method for remote members), so introducing new capturing parenthesis would break that! But you can use non-capturing parenthesis (?:...) if needed. When changing this parameter, experiment a bit to see what works and what doesn't.

Note: Note that you must use quotes with --crossref-format even if no whitespace is included with the option! For example: --crossref-format "#%@#".

Note: --crossref-format and --explicit-crossref cmd line switches are mutually exclusive! Internally, appledoc uses <?%@>? for cross references matching by default, which makes markers optional. Using --explicit-crossref is equal to using --crossref-format "<%@>" and is in fact just a convenience shortcut for it! If you use both options in command line, the last one found will be used!

Inspect generated HTML or documentation set files

appledoc output generation works in several steps (i.e. generate HTML, generate docset, install docset, etc.). Each steps output files are used as inputs for next step. For performance reasons, files are moved instead of copied between steps by default. Although this makes appledoc a bit more efficient, it may seem strange to see output folder empty when appledoc finishes. If so, just think of --output switch as the path to temporary files used during generation. In most cases these intermediate files are not needed and are later removed manually anyway. However there are occasions where you'd want to inspect output; debugging or archiving for example.

Keep intermediate files

You can tell appledoc to keep intermediate files (i.e. copy instead of move) like this:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--keep-intermediate-files
.

Using this option all intermediate files (i.e. HTML and docset files, including docset description XML files) are kept in output path.

Create HTML only

Alternatively you can tell appledoc to only create HTML files:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--no-create-docset
.

By adding --no-create-docset you instruct appledoc to create HTML and then quit. Using this command line, you'll find HTML files in ~/help/html. This option is useful if you don't need documentation set or want to use external tools for generating it.

Create DocSet only

Similarly you can tell appledoc to create docset but not install it:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--no-install-docset
.

Using this command line you'll find docset files in ~/help/docset. The docset is already indexed with all description xml files used for indexing left so you can inspect them (it's --install-docset step that deletes these files and cleans up the docset folders). Note that in this case, html directory is moved inside ~/help/docset, alternatively you could use --keep-intermediate-files to keep a copy, as described above.

Quickly validate source code

You can also disable whole output generation step by using --no-create-html switch:

appledoc
--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
--no-create-html
.

This effectively disables any output generation and only invokes source code parsing and comments processing. As generation phase takes most time (typically more than 90%!), this option is useful for quick validation of your comments for unknown cross references and similar. It may come handy to include it as a regular build phase for larger targets to validate your comments and then manually invoke generation before releasing.

Note that you can omit --output in this case; appledoc will warn you about it but will use current path. As it doesn't generate any output, it doesn't matter in this case. However it's not recommended to do so, as in case you'll copy the command line in the future for actual output generation and forget about adding output path, you may "pollute" your source folder or get output files created at some unexpected path. You can easily clean it up, but it's better to be safe...