Using Appledocs to generate documentation

Question

I apologize for the simplicity of my question, but I was trying to generate documentation using Appledocs (https://github.com/tomaz/appledoc#quick-install)

I'm not sure how exactly to get it setup. The way I do it is:

I clone the github repo and then install appledocs using the install script (I confirm this using appledocs --help) in the terminal.

However, now how do I actually use this in the sense that I have my project in xcode:

how do I generate the documentation file
where is it generated?

score 15 · Answer 1 · answered Mar 04 '13 at 16:08

What I always do is add a new target to my project which can generate documentation. You can go to your project build phases and click on 'Add Target'. Choose Aggregate under Other and give it some name (e.g. ProjectDocumentation).

Still on the build phases tab go to 'Add build phase' and click 'Add run script'. You can now paste the following and adjust it to your own settings:

/usr/local/bin/appledoc \
--project-name HereProjectName \
--project-company "HereProjectCompany" \
--company-id com.companyName \
--keep-undocumented-objects \
--keep-undocumented-members \
--search-undocumented-doc \
--exit-threshold 2 \
--ignore .m \
--output "AppleDoc" .

I use the ignore *.m because I only only write documentation in my header files. Documentation in my *.m files is for myself only (and thus private). When you build this target, the documentation is generated as a XCode docset. This is accessible by alt-click on a class name. Check out the AppleDoc website for commenting syntax.

For explanation of the command-line options checkout the appledoc --help command.

I made `--project-name` dynamic, but I can't find any similar variables for the other 2 fields. Help D: — Alexander, Aug 19 '14 at 03:28

score 3 · Answer 2 · answered Mar 04 '13 at 17:29

for instance, like this, it is a valid header with source code documentation for the latests Appledoc.

//
//  GSUserDefaults.h
//
//  Created by Gabor Szabo on 30/01/2013.
//
//

#import <Foundation/Foundation.h>


/*!
 @discussion This class manages the user defaults on the device with some extra convenient methods.

 ## Version information

 __Version__: 1.0

 __Found__: 2013-01-30

 __Last update__: 2013-01-30

 __Developer__: Gabor Szabo, TMTI Ltd.

 */

#pragma mark - Interface

@interface GSUserDefaults : NSObject {

}

#pragma mark - Class Methods

#pragma mark - Getters

/// @name Getter methods

/*!
 @abstract Returns the value for the key.
 @discussion It reads the values from the `NSUserDefaults`.
 @param key The key, it must be not `nil`.
 @return The value object for the key.
 @exception NSException Thrown when the key is `nil`.
 @since 1.0+
 */
+ (id)valueForKey:(NSString *)key;

/*!
 @abstract Returns a value collection for the keys.
 @discussion It reads the values from the `NSUserDefaults`.
 @param keys The set of keys, which are affected.
 @return The value collection for the desired keys.
 @exception NSException Thrown when the key is `nil`.
 @since 1.0+
 */
+ (NSDictionary *)valuesForKeys:(NSSet *)keys;

#pragma mark - Setters

/// @name Setter methods

/*!
 @abstract Sets a value for the selected key.
 @discussion The value always will be overridden. It sets the value to the `NSUserDefaults`.
 @param value The value object, it can be `nil`, in case of `nil` the key will be removed from the `NSUserDefaults`.
 @param key The key for the value, it cannot be `nil`.
 @exception NSException Thrown when the key is `nil`.
 @since 1.0+
 */
+ (void)setValue:(id)value forKey:(NSString *)key;

/*!
 @abstract Sets `nil` values for the selected keys.
 @discussion The value always will be overridden. It removs the from the `NSUserDefaults`.
 @param keys The set of keys, which are affected.
 @since 1.0+
 */
+ (void)setNilValueForKeys:(NSSet *)keys;

/*!
 @abstract Sets a default value for the selected keys.
 @discussion It the key already exists, it won't be overridden, if the value was `nil` for the key, the key gets the value. It sets the values to the `NSUserDefaults`.
 @param defaultValue The value object, it could be `nil`, in case of the `nil` just nothing will happen, the keys won't be removed.
 @param keys The set of keys, which are affected.
 @since 1.0+
 */
+ (void)setDefaultValue:(id)defaultValue forKeys:(NSSet *)keys;

/*!
 @abstract Sets the value for the selected keys.
 @discussion The values always will be overridden, if the value was `nil` for the key, the key gets the value. It sets the values to the `NSUserDefaults`.
 @param value The value object, it can be `nil`, in case of `nil` the key will be removed from the `NSUserDefaults`.
 @param keys The set of keys, which are affected.
 @since 1.0+
 */
+ (void)setValue:(id)value forKeys:(NSSet *)keys;

@end

that way is the exact same as it would be for the @interface. — holex, May 07 '14 at 12:33

score -1 · Answer 3 · answered Mar 04 '13 at 16:10

The recommended way is to clone GitHub project and compile the tool from Xcode. As cloning GitHub project will create the link to the main repository, it greatly simplifies future upgrading too. To install, type the following in the Terminal:

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

This creates appledoc directory. Within you can find appledoc.xcodeproj Xcode project; open it and compile appledoc target - this should work out of the box, however your system must meet minimum system requirements, see below. I recommend you copy resulting appledoc executable from build directory to one of the directories in your path (echo $PATH) to make it easily accessible.

Optional: Appledoc is selfcontained and contains the necessary template files. IF you want to modify these default from Templates subdirectory to one of the expected locations:

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

for more information visit

This answer doesn't seem very useful, the asker has already located the quick install guide, and this seems to be little more than a copy-paste of that. — Connor, Jul 17 '15 at 22:08

Using Appledocs to generate documentation

3 Answers3