index

Settings and parameters

appledoc has been designed to keep the command line as simple as possible. On the other hand, it offers many command line switches as parameters for you to refine generated output. However only a handful of these parameters are unique from project to project, most of them are common to many projects - company name, documentation set information, etc. To strike the balance, appledoc uses sensible defaults plus it allows you specify common parameters as global settings. In fact, there are three layers of settings:

• Factory defaults: These are "hard-wired" into appledoc code and are designed to be as useful as possible.
• Global settings: Some of the defaults cannot be pre-configured, but are usually common to many of the projects; company name for example. Global settings override factory defaults.
• Project settings: Similar to global settings, project settings allow you to specify appledoc arguments through a file instead of command line on a per-project basis. Project settings override factory defaults and global settings
• Command line switches: You can override factory defaults, global settings and project settings through command line switches.

You can change all parameters provided by appledoc through any of the above mentioned layers. To make your job simpler, global and project settings files use the same names for keys as command line switches. To discover what switches/settings are available, use:

appledoc --help

Most command line switches require a parameter of certain type as indicated in help output. Boolean switches don't use parameter, however they can be prefixed with --no- string to opt them out; see appledoc help output to identify these switches. This is especially useful to disable factory default or global/project setting. For example: to enable doc set installation, you would use --install-docset, and to disable it: --no-install-docset.

Global settings

Global settings are configured through a standard plist file. The path of the global settings file is specified through --templates command line switch - the same switch used for giving the path to template files (HTML and CSS files for example) too. Global settings file should be located at the root path of template files, while templates themselves are usually located in subdirs. As it would be tedious to specify this path for every run, appledoc uses two predefined paths for locating these files:

• ~/Library/Application Support/appledoc
• ~/.appledoc

The paths are searched in the given order - if both exist, the first one will be used. If none of these paths exist, or you want to specify another path, you must use --templates command line argument. In any case, the file must be named GlobalSettings.plist. If it's found in the template path used (either one of the predefined paths or the path from command line), it is loaded and any valid settings found are used for overriding factory defaults.

Global settings use exactly the same arguments as command line, so you don't have to remember another set of keys! Use appledoc --help to see the list of all possible keys. However due to the way plists work, there are few simple rules:

• Settings that can be passed multiple times (--ignore for example) should be specified as an array under a single key with the name of the settings.
• Boolean settings should be given in their "normal" form and their value specified with either true or false value (i.e. there's no need to use --no- prefix).
• All other settings should be strings or numbers - depending the value, check appledoc --help for details.

An example of the plist file:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>--ignore</key>
	<array>
		<string>ThirdParty</string>
		<string>Libraries</string>
		<string>Frameworks</string>
		<string>Testing</string>
	</array>
	<key>--project-company</key>
	<string>Gentle Bytes</string>
	<key>--company-id</key>
	<string>com.gentlebytes</string>
	<key>--create-docset</key>
	<true/>
	<key>--install-docset</key>
	<false/>
	<key>--verbose</key>
	<string>4</string>
	<key>--logformat</key>
	<integer>1</integer>
</dict>
</plist>

Most commonly used global settings include --project-company, --company-id, --verbose, --logformat and similar. These are all settings that are ussually constant between the projects and would otherwise require repeating command line switches on every run. Of course you can still override them on specific projects if needed!

Project settings

Project settings are similar to global settings. In fact, they use exactly the same file format, so above information applies here as well. There are three main differences:

• Project settings don't use special command line switch or predefined path to load them; instead you simply specify the path to the settings file or directory including the file, the same way as any other source path.
• Project settings file allows you specifying any number of input paths.
• Project settings file allows you specifying templates path.

Let's see these in detail:

Implicit import

Every directory given to appledoc command line, after all the switches, is checked for AppledocSettings.plist file. If found, the file is considered as project settings and it's parameters are injected to appledoc settings. The same path is also used to search for source files, so you don't have to list any input files within settings in this case (i.e. in the simplest case appledoc . would be enough). If you'd like to use a different name, you must include file name too; in such case you can use any filename, but you must use .plist extension and must include at least one input path, either through the settings file or with additional command line argument(s). For example: appledoc ~/Project/Settings.plist ~/Project/src

Source input paths

You can embed input paths directly within project settings file to even further simplify command line. This is equivalent to specifying paths on the command line (at the end of the argument list), but the --input setting is specific to project settings files and can only be used here (using it in global templates or command line will result in runtime errors!). Here's an example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
	"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>--input</key>
	<array>
		<string>~/External/Path</string>
		<string>/usr/local/include</string>
		<string>.</string>
		<string>../src</string>
		<string>./MyFile.h</string>
		<string>MyFile.h</string>
	</array>
</dict>
</plist>

As you can see, you can use any number of paths here. There are subtle differences of how these paths are handled though:

• If a path starts with ~ or /, it is considered as absolute and is used exactly as typed. These are the first two strings in above example.
• Any other path is considered relative to the directory where the project setting file is found. Such a path is appended to the directory. These include paths starting with . or .. as shown in the last 4 strings in the above example.

Use custom templates

Finally, project settings allow you specifying --templates parameter so you can use arbitrary location for your template files. This is useful if you'd like to include templates with your project files, so that your users wouldn't need to copy them to predefined locations.

Settings placeholder strings

To avoid repetition and simplify command line even further, many settings allow you specify placeholder strings that are replaced with actual values during runtime. Note that all settings that can use these placeholders are marked in help output by running appledoc --help. This works regardless of whether the setting value came from factory defaults, global setting or command line switch!

Main placeholders

Commonly used placeholders are:

• %PROJECT: Replaced with the value of --project-name.
• %PROJECTID: Replaced with normalized value (see below) of --project-name.
• %COMPANY: Replaced with the value of --project-company.
• %COMPANYID: Replaced with the value of --company-id.
• %VERSION: Replaced with the value of --project-version.
• %VERSIONID: Replaced with normalized value (see below) of --project-version.
• %YEAR: Replaced with current year in format yyyy.
• %UPDATEDATE: Replaced with current date in format yyyy-MM-dd.

Normalized values are actual strings where all whitespace is replaced with minus signs. So "My Great Project" would become "My-Great-Project".

Other placeholders

Other available placehoders are (Note: Due to the usage of above mentioned placeholders as default values you should rarely if ever need supply custom values through command line - default values should result in sensible results! However all customization nuts, knock yourself out :)):

• %DOCSETBUNDLEFILENAME: Replaced with the value of --docset-bundle-filename. Defaults to %COMPANYID.%PROJECTID.docset, which results into something like com.gentlebytes.appledoc.docset.
• %DOCSETATOMFILENAME: Replaced with the value of --docset-atom-filename. Defaults to %COMPANYID.%PROJECTID.atom, which results into something like com.gentlebytes.appledoc.atom.
• %DOCSETPACKAGEFILENAME: Replaced with the value of --docset-package-filename. Defaults to %COMPANYID.%PROJECTID-%VERSIONID.xar, which results into something like com.gentlebytes.appledoc-2.0.xar.

If you're wondering why these placeholders exist, they come extremly handy when preparing documentation set for publishing.

Command line examples

Below find links to various command line example sections. Examples are meant to be used as tutorials, giving command line switches and some explanation of how they work together.

General topics

• Basic command line examples: Includes examples of minimum command line, parsing from multiple locations and ignoring paths. Suitable for new users to get them going. This reading is prerequisite for the rest.

• Advanced command line examples: Covers advanced topics, such as preparing documentation sets for publishing, and switches that change the way undocumented entities are handled, how to merge data and get control over cross references detection.

• Including custom documentation: Explains how you can include custom documentation into generated HTML and documentation sets. After reading this section, you'll be able to include arbitrary files, media and documentation such as companion guides. You'll also learn how you can link to these documents from the rest of the documentation.

• Xcode integration: Examples of how you can integrate appledoc within Xcode workflow.

Common tips

• You can use --print-settings option to print values of all settings used for the current session. Settings are printed after replacing placeholder values, so this makes it perfect for checking various paths and similar. Or for debugging when things are not working according to your expectations. For example, it can save you hours of banging your head on a wall to only realize you've forgotten overriding some global setting (it sure saved our heads a lot :). This option has negligible affect to performance, so you can simply include it in your global settings to avoid command line clutter.

• You can use --repeat-first-par option to enable or disable repeating first paragraph in methods and properties discussion section. By default appledoc repeats first paragraph, but you can disable it with --no-repeat-first-par. Important: Note that discussion section is omitted for methods or properties that only have a single paragraph, even if repeating is enabled!