Tag

appledoc

3rd Party Technologies Every iOS Developer Should Use – Part 1- Appledoc

By | iOS, Mobile | 2 Comments

As part of a new series, we’re going to be looking at various tools that our App Experts have encountered during our mobile app experience that we feel no iOS developer should be without. To get the ball rolling, we have the solution to every developers most dreaded task, documentation. So what is this remarkable tool? The answer is Appledoc.

What is it?

Appledoc is a tool for building and maintaining documentation for your apps/libraries. After a quick setup, it compiles together your code-comments into a fully Apple-styled docset that can be kept up-to-date with a simple press of a button. For hassle free documentation on the fly, it’s the best option around for iOS developers.

Setup

Appledoc has a quick and easy installation process. First things first, you’ll need to download it:

You can download it manually from the developers’ github or just run this simple command in the terminal:

git clone git://github.com/tomaz/appledoc.git

Next up, install. To install appledoc use the following command:

sudo sh install-appledoc.sh

Add the build script to your project:

Once Appledoc is installed, you’ll need to add it into your project (note: you’ll need to repeat this step for every new project you start if you want to use Appledoc with it).

Select your project in the Project Navigator and select the plus icon at the bottom left of the view window to add a new target. We’re going to add our script as an ‘Aggregate’ target, which can be found in the ‘Other’ tab. For this new target, go to the ‘Build Phases’ tab and add a new ‘Run Script Build Phase’ by selecting the plus sign in the top left of the view window. Paste the following script into this new phase’s script window:

#appledoc Xcode script
 # Start constants
 company="YOURCOMPANYHERE";
 companyID="com.YOURCOMPANYHERE";
 companyURL="http://YOURCOMPANYHERE.com";
 target="iphoneos";
 outputPath="~/help";
 # End constants
 /usr/local/bin/appledoc \
 --project-name "${PROJECT_NAME}" \
 --project-company "${company}" \
 --company-id "${companyID}" \
 --docset-atom-filename "${company}.atom" \
 --docset-feed-url "${companyURL}/${company}/%DOCSETATOMFILENAME" \
 --docset-package-url "${companyURL}/${company}/%DOCSETPACKAGEFILENAME" \
 --docset-fallback-url "${companyURL}/${company}" \
 --output "${outputPath}" \
 --publish-docset \
 --docset-platform-family "${target}" \
 --logformat xcode \
 --keep-intermediate-files \
 --no-repeat-first-par \
 --no-warn-invalid-crossref \
 --exit-threshold 2 \
 "${PROJECT_DIR}"

Utilization

With all of that done, all that’s remaining is to build your new target and your Docset will be created.

Appledoc has it’s own commenting syntax to distinguish between code comments and documentation. So if we want to add a comment to our documentation, we’ll use either /// or /** as opposed to the usual // or /*.

When writing the documentation for class methods, we’re going to get prompted to provide documentation for any parameters and returned objects. We can do this using @param <parameterName> and @return. For example:

/**Provides functionality to do stuff with a string
@param input String value passed into our method to do stuff with
@return Returns the result of the stuff we did to our string */
-(NSString *)doStuffWithString:(NSString *)input

That’s the basics of Appledocs! There’s a lot more to the syntax — Part 1 of this series is meant to show developers enough to get started. If you’re looking for additional information,  you can find a comprehensive document here. What are some of the major challenges you’ve faced with documentation as an iOS mobile app developer? Give us a shout in the comments section below and be sure to check back for our next post in this series!