appledoc docs examples basic

Basic command line examples

Minimum command line

This is the minimum set of parameters appledoc requires in order to be able generate any output. Each command line switch is written in it's own line to make the output more readable; switches should be delimited with space normally!

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

Parses files from current directory and generates HTML files in the given output path. HTML files are then used to generate documentation set (in given output path) and this is finally moved to shared folder where Xcode searches documentation sets. Xcode is also instructed to reload documentation, so any change is immediately visible.

Parsing from multiple locations

All command line arguments after the last switch are considered as source paths. Each path is validated and as long as all are valid directory or file names, appledoc uses them for parsing. If the path is directory, it's recursively parsed for all source files. If path is file, it's parsed as source file:

--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/help
~/Projects/Common
~/Projects/Frameworks/SomeHeader.h
~/Projects/Frameworks/AnotherFile.m
.

This extends previous example by including all files from ~/Projects/Common directory and it's subdirectories and ~/Projects/Frameworks/SomeHeader.h and ~/Projects/Frameworks/AnotherFile.m files besides the files from current directory.

This allows you to include files regardless of where they reside on your computer. For example, it may be used to include headers from frameworks or libraries your project uses or simply to only parse a subset of your project files.

Ignore paths

You can instruct appledoc to ignore any number of paths or files using --ignore switches. This is useful if your project includes third party source files for example (note that it's recommended to put these files into a subfolder to simplify ignoring, for example you could have ThirdParty folder under your main project dir and keep all third party source code as subdirs within):

--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--output ~/Projects/Help/appledoc
--ignore Common
--ignore .m
.

Using this command line would effectively ignore all files in ./Common including all subdirectories. Additionally it would ignore all files and directories with extension .m.

Each --ignore switch takes a single path that should be ignored while parsing. It works very simply: each directory or file found in the given source paths (. in this case) is checked and if it ends with one of the ignore values, the path is skipped. Or put in other words: [NSString hasSuffix:] message is sent to each string containing source file or directory to validate ignored files.

Important: Note that --ignore strings don't accept * and ? chars for wildcards matching! However if the string starts with a star (*), the star is removed, so --ignore *.m is internally translated to --ignore .m for your convenience. But star in the middle doesn't work, so this --ignore path/subpath/*.m would not ignore all .m files in path/subpath as expected - in fact, it would only match files or directories which names end with path/subpath/*.m (effectively matching nothing)!

Markdown compatibility

appledoc should be fully Markdown compatible, but as it needs to scan the comment texts prior to passing it to Markdown processor (to inject cross references among other things), which may result in some incosistencies. You can use these command line switches to control output:

--project-name appledoc
--project-company "Gentle Bytes"
--company-id com.gentlebytes
--use-single-star
--output ~/help
.

• --use-single-star: Controls how single star is handled, defaults to off. If the switch is used, single stars are automatically converted to double stars, so Markdown processor can make the text bold. However this may break unordered lists prefixed by star:

   * item1
   * item2
  

  In this case, the two stars would be converted to bold markers, hence the output wouldn't be unordered list. By disabling single star usage, you can prevent this from happening.

  Important: Historically, appledoc allowed single stars as bold, but from version 2.0.5 (build 737), which introduced this switch, defaults have changed and the option is disabled by default! You have to manually enable it to keep it backwards compatible!

Project settings

You can use project settings file to gather all project specific settings and even further simplify command line. In it's simplest form you could only have:

appledoc .

This command line would check current directory for a file AppledocSettings.plist. If found, the file would be read in and all parameters from it used for generating the documentation. Note that, as the path argument was a directory, current dir would also be searched for any source file. Of course you can use any directory instead of current one: appledoc ~/MyProject.

If you'd like to use different file name, you need to specify the path to the file:

appledoc ~/path/project.plist

This parses the given file as project settings file and injects all parameters from it. You have freedom to choose any file name this way, but you must use .plist extension in order for appledoc distinguish it from a source file. Note that as in this example we didn't specify any input source file or folder, you must either provide them via the given project file or through additional command line switch like this:

appledoc ~/path/project.plist ~/MyProject