tomaz / appledoc

Objective-c code Apple style documentation set generator.

About appledoc

IMPORTANT NOTICE: collaborators needed

appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments. It's designed to take as readable source code comments as possible for the input and use comments as well as surrounding source code to generate visually appealing documentation in the form of HTML as well as fully indexed and browsable Xcode documentation set. Although there are several tools that can create HTML documentation for Objective-C, all of those known to me fall short in meeting the minimum of goals described below.

Main goals of appledoc:

• Human-readable source code comments.
• Simple cross references to objects and members.
• Generate Apple-like source code HTML documentation.
• Generate and install fully indexed and browsable Xcode documentation set.
• Single tool to drive generation from source code parsing to documentation set installation.
• Easily customizable output.
• 100% Objective-C implementation for easy debugging.

To make your experience with appledoc as smooth as possible, we warmly suggest reading this whole document as well as all online documentation mentioned in "using appledoc" section below!

Usage of appledoc is allowed under the terms listed in LICENSE section at the bottom of this file!

Want to keep updated? Follow us on Twitter - @gentlebytes.

Quick install

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.xcworkspace Xcode workspace; 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

You can also use install-appledoc.sh script to perform quick installation. Open Terminal and switch to appledoc directory. Type following command:

sudo sh install-appledoc.sh (if you need templates add '-t default')

It compiles appledoc and installs its binary to /usr/local/bin and templates (if wanted) to ~/.appledoc by default. You can override this directories with -b and -t options respectively. For example:

sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

Alternatively with Homebrew:

brew install appledoc

Homebrew does not install templates by default.

Using appledoc

Use appledoc --help to see the list of all command line switches. Read more about appledoc on appledoc site. Also read wiki pages for some more in-depth articles.

Use appledoc Google group as a forum for questions on usage or other general questions.

Use appledoc issues page to submit bug and feature requests. Before submitting new issues, check the forums to see if your question is answered there - unless you can confirm your issue as a new feature request or a bug, you should start at the forum to keep GitHub issues clean. Also read through issues to see if the issue is already there and vote on it or add a comment (don't forget about closed issues).

Installation tips

To keep up to date, just go to Terminal and cd into appledoc directory, issue git pull and recompile appledoc.xcodeproj. Don't forget to overwrite appledoc executable you've copied to $PATH :)

If you also want to compile and run AppledocTests (unit tests) target, you need to copy all the frameworks indicated within Libraries & Frameworks group to shared frameworks directory before building unit tests target! This is not required for building the appledoc tool itself.

Integrating with Xcode

You can setup Xcode to automate appledoc document creation. Find out how using a Run Script and your project's Build Phases.

Docset usage tips

Pre-generated documentation and docsets for most Cocoa frameworks are available at:

• CocoaDocs

Once you have a docset, you might want to use it with a documentation browser:

• Xcode
• Dash

Troubleshooting

Have problems? This is what you can do to troubleshoot:

1. Make sure you have the latest appledoc version. Try git pull and run with latest version again.
2. IF you have template files installed, make sure you're using the latest - delete the predefined folders and have appledoc copy the files from its embedded archive again (see Quick Install section above).
3. Increase verbosity level with --verbose command line switch. Default level is 2, but you can progressively increment verbosity up to 6 with each level giving you more detailed information. As this will give you a lot more information, you may want to concentrate only on specific set of source files you have problem with. Note that increasing verbosity will result in slower performance so using levels above 4 for every day use is not recommended.
4. Appledoc is open source project! You have all the source code available, so run it from Xcode. You can setup Xcode to pass the desired command line arguments and add breakpoints to help you isolate your issue. If you feel you'd like to contribute more to community, you are welcome to fork the project on GitHub and add features to it. Keep us posted so we can add these features to main repository as well - include unit tests if possible.
5. If you think you found a bug or want to request new feature, go to appledoc issues page. First read existing issues to see if there is already a request there (if you're using master branch, also read closed issues as your request may have already been covered but isn't yet merged on master branch). You can vote on existing requests to help us decide which features to concentrate on or you can add a comment to aid in solving it. If you don't find the request there, create a new issue; include parts of source files that give you problems if possible and/or description or steps that lead to it.
6. If you're having problems with some of your source files and don't want to publish them online, you can contact us through email below. We'll do our best to help you out, but bear in mind appledoc is not commercial product; it's created and maintained in our spare time, so resources are limited.

Developer notes

If you wish to contribute, see the Developer Notes file for short overview of how appledoc works internally.

Minimum system requirements

• Xcode 4.5 or greater for compiling
• OS X 10.7 for compiling and running

License

appledoc is licensed with modified BSD license. In plain language: you're allowed to do whatever you wish with the code, modify, redistribute, embed in your products (free or commercial), but you must include copyright, terms of usage and disclaimer as stated in the license, the same way as any other BSD licensed code. You can of course use documentation generated by appledoc for your products (free or commercial), but you must attribute appledoc either in documentation itself or other appropriate place such as your website.

If for whatever reason you cannot agree to these terms, contact us through contact form on our about page, we'll do our best to help you out you out and find a workable solution!

Copyright (c) 2009-2011, Gentle Bytes All rights reserved.

Redistribution and use in source, binary forms and generated documentation, with or without modification, are permitted provided that the following conditions are met:

• Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

• Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

• Redistributions of documentation generated by appledoc must include attribution to appledoc, either in documentation itself or other appropriate media.

• Neither the name of the appledoc, Gentle Bytes nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Gentle Bytes [email protected]

appledoc's Issues

Method links broken

Currently, the following code:

You normally do not have to need this class directly. Use [SPTextField registerBitmapFontFromFile:] instead. 

Produces this output:

You normally do not have to need this class directly. Use [SPTextField registerBitmapFontFromFile:] You normally do not have to need this class directly. Use [SPTextField registerBitmapFontFromFile:] instead. 

I guess that's a side effect of a recent bugfix.

GBTask.h and GBTask.m - compiler warnings on un-implemented properties

There are a number of warnings on GBTask.h and the private interface defined in GBTask.m. It appears that several properties have been duplicated on both interfaces and there are no matching @synthesize or implementations on GBTask.m

Option to copy intermediate files instead of moving

Hi, I've used the --output to specify an output path and --install-docset to get the results installed in my local xcode. When I check the output path though, it's empty. I was hoping to see a copy of the assembled docset so I could then copy it to my projects dmg files.

Am I missing something or is this a bug?

Typedefs, enums, functions support?

Hi Tomaz,

Thanks for putting appledoc together and making it available.

I'm having a hard time getting typedefs, enums or functions to document themselves. I've tried following the Doxygen examples and tried different settings in the settings file without success. Are these supported in appledoc? If so, would you please provide an example of a typedef enum?

Looking forward to version 2!

Brad

Output path may not be '.'

When I use the following option:

--output .

produces this error:

Generation step 1/1 failed: GBHTMLOutputGenerator failed copying template files to output, aborting!
The file “” couldn’t be saved.

It works, however, with this workaround (when 'doc' is the current dir)

--output ../doc

"--ignore" with ".m" as argument does not work any more

If I use the following command line argument:
--ignore .m
then the .m files are no longer ignored (that worked in the stable version). There has to be at least one character before the dot for it to work.

#pragma mark -

The following code:

#pragma mark -
#pragma mark Something

/**
 * Reloads the content in the visible view controller.
 */
- (void)reload;

is parsed as a method with the signature:

#:pragma:mark:Something:-:(:void:):reload:

and the documentation block is ignored.

Documentation formatting documentation

Hi, Is there a wiki page or something that outlines the tags that appledoc looks for?

It appears to be finding the doxygen ones I used for appledoc V1, but I was not really a fan of those. I'd like a wiki page that outlines the following:

• The syntax options: headerdoc style, doxygen style? other ?
• Basic formatting - paragraphs, bold, italic.
• Linking - properties, methods, class, protocols, etc.
• How to embed code samples - inline and block.

thanks.
Derek

How are the Task sections changed in docsets?

So far so good. The layout of the docsets is excellent.

Maybe this is covered somewhere, apologies if it is, but how do you modify the Tasks sections of the documentation? Under the Tasks heading, I only see Other and Other. I expected to be able to producing something along the lines of:

Tasks:

• Initializing a Class
• Creating, Copying, and Deallocating Objects
• Identifying Classes
• etc.

but I only see:

Tasks:

• Other
• Other

I have a screen shot to make this more clear, but I don't see an obvious way to upload it to this case (this is my first time working with github).

Thanks,

jjm

Private comments

A comment may be marked as private. These comment would only be used for output generation if certain command line switch was used. If not, the commented object would simply be handled as if not commented. If a class, category or protocol would be marked as private, all of it's members would also be considered private regardless of whether they are specifically marked as private or not.

@param and @return only work if there is an empty line above them

It would be great if that wasn't necessary - it looks weird to some when the paragraph above is just one line.

Categories trigger duplication of Tasks

Here's a quick example:
NSDictionary+dUsefulStuff.h:

/**
 * This category adds messages to the NSDictionary class to allow calls to dictinary functions using int's as keys.
 */
@interface NSDictionary (dUsefulStuff)
/**
 * Returns an object based on an int key.
 */
- (id) objectForIntKey:(int)aIntKey;
@end

NSDictionary+dUsefulStuff.m:

#import "NSDictionary+dUsefulStuff.h"
@implementation NSDictionary (dUsefulStuff)
- (id) objectForIntKey:(int)aIntKey {
    return [self objectForKey:[NSNumber numberWithInteger:aIntKey]];
}
@end

In the resulting doco we get:

---

Tasks

Other Methods

• objectForIntKey:

Other Methods

• objectForIntKey:

---

As you can see, the method is being listed twice. I've checked other categories and the all appear to be doing this. Classes that make use of categories internally, for example @interface SomeClass() are doing something slightly different. The methods and properties are still being listed twice, but under the name "Extension Methods". Here's a cut'n'paste from a class showing this.

Tasks

Properties

delegate
scaleType
rating

Icons

onRatingImage
offRatingImage
halfRatingImage

Bubble

bubble

Extension Methods

delegate
scaleType
rating
onRatingImage
offRatingImage
halfRatingImage
bubble

As you can see it's taken all the properties defined under Properties, Icons and Bubble and re-listed them under Extension Methods. So far the only difference between this class and any other class appears to be that it uses an internal category to add further private methods to the .m file. I.e.

@interface DCUIRating ()
- (void) calculateRatingWithTouch:(UITouch *)aTouch;
- (void) popBubbleAtTouch:(UITouch *)atTouch;
- (void) hideBubble;
- (void) updateBubble;
@end

@implementation DCUIRating
...

Templates not found

For some reason, the templates in the default directory are not found. When I start appledoc normally, I get this error:

Generation step 1/1 failed: GBHTMLOutputGenerator failed generaing output, aborting!
Object template file 'object-template.html' is missing at '(null)'!

However, when I add the following option, it works.

--templates "~/Library/Application Support/appledoc"

Add syntax for links that don't show their address

It would be great to have a syntax for links that does not show the address of the link in the output - e.g. like this:

* Go to [Google](http://www.google.at)

Template path is not set if Globals.plist doesn't exist

First of all, nice work!

I think I've found several bugs:

The template path is not set if Globals.plist does not exist. Diff:
diff --git a/CommandLineParser.m b/CommandLineParser.m
index a483a51..5d031d3 100644
--- a/CommandLineParser.m +++ b/CommandLineParser.m @@ -609,7 +609,6 @@ instead.
// will override factory settings. Then set the path to the templates folder.
NSDictionary* globals = [Systemator readPropertyListFromFile:globalParametersFile];
[parameters addEntriesFromDictionary:globals];
[parameters setObject:path forKey:kTKCmdTemplatesPathKey];
}
@catch (NSException* e)
{
@@ -617,6 +616,9 @@ instead.
return NO;
}
}
[parameters setObject:path forKey:kTKCmdTemplatesPathKey];
return YES;
}
if --clean-temp-files or --clean-before-build is given, the first run of appledoc would report such an error when generating docset:
2010-07-15 15:56:38.220 appledoc[9657:903] Exiting due to exception: The file couldn’t be opened.
15:56:38:215 [ERROR ] | Failed enumerating files at '(null)'!

PS: it would be more convenient for bug reporting if you enable issue tracker in github.

Possibility to add comment to task section

Certain section titles have comments attached in Apple documentation. appledoc could also allow such comments.

For example see "Handling File Operations" section for NSFileManager at http://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSFileManager_Class/Reference/Reference.html#//apple_ref/doc/uid/20000305-SW31.

Documentation of Properties?

Hi Tomaz. I see you've been working on the project again. Thank you for your work.

I've started putting some effort into documenting the project I'm working on. I'm mainly interested in the docset generation and I'm happy to say it shows up and looks great in XCode 4. However, I get Overview, Tasks, and Instance methods, documented from my code comments, but haven't been able to get class properties. Any idea what I'm missing?

I get Overview from comments placed above the interface declaration in the class header file, but comments above the viewDidLoad method in the implementation file do not appear in the documentation. I wonder if methods inherited from the superclass are not documented?

Also, in Apple documentation, some classes have multiple headings under Tasks. How is that accomplished with appledoc?

Thanks again.

Version information directives

Special directives for specifying version information: for example @introducedin, @deprecatedin, @removedafter. This should be extracted in HTML and/or to documentation set.

Class hierarchy page

Add class hierarchy page generation.

Punctuation and parentheses disrupt link-generation

Names of classes and methods are not recognized as links when they are followed by punctuation marks or surrounded by parentheses, like this:

Your string is a NSString.
You can't change immutalbe strings (NSString).

Cross reference from method declaration line

Method declaration line (i.e. "- (void)doSomethingWith:(id)value") could include cross references to known objects in method result and argument types. Probably links should use same color as the rest of the text to avoid visual noise and only show underline if hovered.

Command line is order sensitive

With this command line:

../tools/appledoc/appledoc --templates ../tools/appledoc/Templates --install-docset YES --output build --project-name dUsefulStuff --project-company "Derek Clarkson" --templates ../tools/appledoc/Templates --company-id au.com.derek.clarkson src/code 

I get the following error:

ERROR: AppledocException: Path or file 'au.com.derek.clarkson' doesn't exist!

If I then move the --company-id parameters to before the --templates parameters, everything works just fine. I've found the same with several other parameters. It would appear that some (but not all) parameters are order sensitive and appledoc doesn't like then appearing after templates.

Exception with using __attribute__((deprecated)) on property

Thanks for your appledoc effort.
I was curious if we could use the experimental version to throw on the headers for our iPhone SDK.
Unfortunately it does not like yet API deprecation,

an header with

@Property(nonatomic, retain, readonly) SLCMoney *balance attribute((deprecated));

@Property (nonatomic, retain, readonly) SLCScore* highScore attribute((deprecated));

will throw an exception:

2010-12-14 18:23:43.619 appledoc[39836:a0f] *** Assertion failure in -[GBMethodData mergeDataFromObject:], /Volumes/Scoreloop+GIT/Material/appledoc/Model/GBMethodData.m:180

(gdb) po [source methodResultTypes]
<NSCFArray 0x200065100>(
SLCScore,
*,
highScore,
attribute,
(,
(,
deprecated,
)
)

(gdb) po [self methodResultTypes]
<NSCFArray 0x200356d80>(
SLCMoney,
*,
balance,
attribute,
(,
(,
deprecated,
)
)

Best regards, thomas

Feature: ignore implementations

I'm currently using `--no-warn-undocumented-member' because I put my documentation in the headers and my implementations often contain internal methods. Without suppressing this warning I get a lot of warning messages about the implementation because of the lack of doco there.

I'd much rather be able to tell appledoc to ignore implementations and just use the headers as the source. Therefore something like --ignore-implementations as a command line switch.

Omit links when in linked to section

In the description of the priority method in DCTConnectionController, I use the word priority a lot while discussing what the method does. While I love that theres a load of cross-linking between methods, would it be possible to stop links occurring if they are to be put in the description for the thing they are linking to?

Allow blocks of code

Firstly, thanks for appledoc2, it's AWESOME.

It'd be really great to have whole blocks of code so that you can show example usage. At the moment I'm using multiple code lines in my DCTConnectionController documentation.

Allow to mark code blocks with spaces

Some developers uses spaces instead of tabs normally (as can be set in Xcode).

Currently, code blocks are marked by starting with a tab, which is difficult to do if Xcode has the above setting. It would be great if you allowed, say, 4 spaces instead of a tab to mark source code.

Recognize plural forms of classes and members

It would be great if the automatic linking of classes and members would recognize plural forms, at least for those cases where the plural form adds a simple "s" (like the pluralize method of Ruby on Rails)

Interface definition in #ifdef: class description not recognized

This is a rather obscure problem - consider it low priority!

I have a class like this:

/** Class description */
#ifdef __IPHONE_4_0
@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
#else
@interface SPBitmapFont : NSObject
#endif
{
    // ...
}

// ...
@end

In that case, the class description is not recognized.

I guess something like that won't happen very often - but a change in the iOS SDK forces me to do it.

If any other user has a similar problem: you can use the following workaround:

#if 0
/** Class description */
@interface SPBitmapFont
#endif

#ifdef __IPHONE_4_0
@interface SPBitmapFont : NSObject <NSXMLParserDelegate>
#else
// ... -> continue as before

Table of Contents frame like in Apple documentation

It would be great if an Apple-Style table of contents sidebar could be implemented. I believe this could probably be done with the template system, but I'm not familiar enough with it myself. I'll do some more looking...

Create an Atom feed so that Xcode can load docset from URL

It would be great if that was possible. Here is an example of how this would look like:

Like this one:
http://aptocore.com/downloads/cocos2d/cocos2d-iphone-doc.atom

That way, people can add it to Xcode via Xcode / Preferences / Documentation / Add Publisher.

A way to get in control which word is a link and which isn't

At present all words that are also valid class, category, protocol or member names are converted to cross reference to that object. If generic names are used for objects, all occurences of these words are considered as cross reference within appledoc. And this is not what the user intended.

For example protocols word used that is used a lot within documentation for appledoc's own GBAdoptedProtocolsProvider class is many times used as a "normal" word protocols, not as a reference to class' protocols property, however appledoc all occurences of the work treats as cross reference.

As appledoc already allows links being optionally embedded within <>, it could optionally require all parts that should be treated as potential cross references embedded within these chars. Perhaps with a command line switch that can change this behavior. On the other hand source code may become less readable, especially when coupled with styling directives - <protocols> vs protocols for example.

Any suggestion is welcome....

Casing problem for "appledoc_prefix.pch"

I am working on a HFS case-sensitive drive, and I has an issue with the "appledoc_prefix.pch" file. In the project, the "appledoc_prefix.pch" is referenced, but on the disk, it is "appledoc_Prefix.pch". The result is that Xcode complains about not finding the file. Renaming it properly does the trick.

Links in parentheses make parentheses disappear

Links make parentheses disappear.

What about (<http://wwww.google.at>) this?
becomes ->
What about http://wwww.google.at this?

while

What about (http://wwww.google.at) this?
becomes ->
What about http://wwww.google.at) this?

Unexpected Spaces

The following code inserts a space between "Flash" and the comma:

Different to _Adobe Flash_, blah blah!

The same happens here, between the class name and the plural-s.

`SPEventDispatcher`s are blah.

Incorrect case on appledoc_Prefix.pch

Should be appledoc__p_refix.pch

Won't compile on a case sensitive system until fixed.

@name requires own comment section

Not sure if this is a bug or documentation clarification or feature request :-)

Currently @name tags need their own section. For example
/* @name My Hot Properties /
/
* Some property.
*/
@Property (retain, nonatomic) int prop;

I've tried doing this:
/**
* @name My Hot Properties
* Some property.
*/
@Property (retain, nonatomic) int prop;

But it just prefixes the @name My Hot Properties string to the beginning of the comment.

Ideally I'd like it to be picked out and a new group started. The quick fix is to update the documentation to indicate it must be in it's own comment block.

Crash when executing appledoc no matter what I've tried

I've tried to run appledoc on the appledoc code itself but it crashes no matter what I've tried so far. Find the stack trace below. Any hint on how to get this fixed or work arounded would be highly appreciated.

2011-01-11 22:03:26.738 appledoc[3650:903] -[GBTask setLastCommandLine:]: unrecognized selector sent to instance 0x200297d60
Oops, something went wrong...
NSInvalidArgumentException: -[GBTask setLastCommandLine:]: unrecognized selector sent to instance 0x200297d60
@ 0 CoreFoundation 0x00007fff852ff7b4 exceptionPreprocess + 180
@ 1 libobjc.A.dylib 0x00007fff86bc50f3 objc_exception_throw + 45
@ 2 CoreFoundation 0x00007fff85359110 +[NSObject(NSObject) doesNotRecognizeSelector:] + 0
@ 3 CoreFoundation 0x00007fff852d191f __forwarding + 751
@ 4 CoreFoundation 0x00007fff852cda68 _CF_forwarding_prep_0 + 232
@ 5 appledoc 0x000000010005faf8 -[GBTask runCommand:arguments:block:] + 520
@ 6 appledoc 0x000000010005cf72 -[GBDocSetOutputGenerator indexDocSet:] + 338
@ 7 appledoc 0x000000010005ba04 -[GBDocSetOutputGenerator generateOutputWithStore:error:] + 484
@ 8 appledoc 0x0000000100040629 __42-[GBGenerator runGeneratorStepsWithStore:]_block_invoke_0 + 617
@ 9 CoreFoundation 0x00007fff852b86d7 __NSArrayEnumerate + 1399
@ 10 appledoc 0x000000010004033e -[GBGenerator runGeneratorStepsWithStore:] + 542
@ 11 appledoc 0x000000010003ff56 -[GBGenerator generateOutputFromStore:] + 342
@ 12 appledoc 0x000000010000440e -[GBAppledocApplication application:runWithArguments:] + 1662
@ 13 appledoc 0x00000001000021a6 -[DDCliApplication runWithClass:] + 294
@ 14 appledoc 0x00000001000024d8 DDCliAppRunWithClass + 120
@ 15 appledoc 0x0000000100001887 main + 71
@ 16 appledoc 0x0000000100001834 start + 52

Add troubleshooting to readme

Add some basic troubleshooting guide to readme, such as increasing verbose setting etc.

appledoc crashes with [GBAppledocApplication setTemplatesFound:]: unrecognized selector

This is the compiler warning I get during building a release version. Adding @synthesize templatesFound fixes the problem with crashing.
appledoc/Application/GBAppledocApplication.m:80:25: warning: property 'templatesFound' requires method 'templatesFound' to be defined - use @synthesize, @dynamic or provide a method implementation

Xcode's QuickHelp not working with created DocSet

Xcode does not display QuickHelp for the DocSet I created with AppleDoc. The other parts of the Xcode integration work fine - I can see the project in the Help menu and the files are found when I right-click a keyword and choose "Find text in documentation".

It does not seem to a problem with my setup - I asked other people to install my docset, and they reported the same results.

Discussion repeats description

The title sounds enough.

Year and update moment not replaced correctly

I think you mixed up "%" and "$" somewhere in the latest version. Because of that, the replacement of the year and change moment labels at the bottom of the HTML documents does not work.

The documentation also shows "$" instead of "%" in the documentation (section: "Prepare documentation set for publishing").

GBCommentParagraph crash

[GBCommentParagraph stringValue] crashes if the stringValue of one of the contained items is nil.

Fix:

for (GBParagraphItem *item in self.paragraphItems) {
    NSString *string = [item stringValue];
    if( !string ) string = @""; // work around nil item stringValue
    if (item != [self.paragraphItems lastObject] && ![string hasSuffix:@"\n"]) string = [string stringByAppendingString:@"\n"];
    [result appendString:string];
  }

--output directory not being created

I just tried `--output build/appledoc' and appledoc reports:

Generation step 1/2 failed: GBHTMLOutputGenerator failed copying template files to output, aborting!
The operation couldn’t be completed. No such file or directory
No such file or directory

if I manually create the output directory it works.

Allow creating line breaks

Manually adding line breaks with

or

would be great!

Possibility to add arbitrary documentation such as main page

This would not be attached to any class, category or protocol. It should prefferably be completely decoupled from source files - as a set of "external" files created outside picked up by appledoc and copied to output directory.

Ideally, this should be somewhat processed by appledoc for cross references and use the same markdown syntax.

Additionally, there should be a way to link to this static documentation from within standard source code comments. It would also be nice to have it linked as companion guide so that it would also get listed in doc set.

Allow single-line comment *after* the documented line

Doxygen allows to have one-liners at the right of the code. That would be great to save space!

- (void)start; /// starts the engines

'object-template.html' is Missing

Generation step 1/2 failed: GBHTMLOutputGenerator failed generaing output, aborting!
Object template file 'object-template.html' is missing at '(null)'!

Get this result every time. I have verified that the file is there.

Cleanup HTML code

HTML code contains a lot of whitespace. Although this doesn't affect layout in most cases, it does mess blocks and punctuation.