Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Commits on Feb 11, 2011
  1. Merge branch 'development'

  2. Implemented possibility to add arbitrary documentation. Closes #7.

    This was one of much requested features. It allows adding arbitrary files to generated documentation. It's enabled with one or more `--include` switches. All files and directories specified are simply copied to `docs` subfolder within generated HTML files. So basically, you're free to write any HTML or whatever you want included with the generated documentation.
    But the power lies in special "template" files. These are just normal text files which names end with `-template` (for example `document1-template.html). Extension of these files is not important - they will always be converted to .html! The files can reside on any subpath - the path will be preserved. All such files are processed using the same logic as any other comment, so you can use appledoc comment syntax, including cross referencing any object or member. You can also cross reference these files from "normal" comments (or other documents) by simply writing the filename without `-template` and extension. You don't have to deal with subpaths either, these will be automatically picked up for you! [Online documentation]( is not yet updated, will do it shortly.
    At this point, it's basic stuff only. As such it has much potential for future (like adding markdown syntax for headings, images and similar - for now just use HTML tags). But at least it's a start and get's work done for the moment.
    Enjoy and let me know if you find something not working as expected :)
Commits on Feb 4, 2011
  1. Updated build number to 564.

  2. Fixed handling command line arguments with tilde.

    It turns out Xcode 4 GM fails to replace tilde with full path, so I added explicit handling of this.
Commits on Feb 3, 2011
  1. Increased build number to 561.

  2. Fixed short description for comments with single paragraph containing…

    … special blocks. Closes #62.
    The issue was with comments like this one:
    	/** Some text
    	@warning Description
    	- (void)method;
    Although all special blocks (warnings, bugs, examples and lists) are delimited with empty lines from preceding text, they are conceptually part of the same paragraph - they are converted to a paragraph item object and added to the same paragraph as preceding text. The reason for such handling is so that we can add such items to whatever paragraph - like @param or @return description etc. However when creating short description and tooltips for methods, the whole first paragraph (including all special blocks) was used. As from the users point of view, these are clearly delimited with empty line, the resulting documentation contained unexpected tooltips and short descriptions.
    These situations are properly handled now and only the text part of the first paragraph up to the first special block is used for short description and tooltip! Thanks to "BloodDragon" for pointing it out!
    *NOTE:* after implementing this part I noticed that special blocks were not rendered to the documentation in such cases if `--no-repeat-first-par` option was used. A bit more logic was required in such case, so appledoc now properly repeats omitted parts as a first paragraph of the description paragraphs of a comment!
    *IMPORTANT:* This commit requires updating template files!
Commits on Feb 2, 2011
  1. Added some description to GBComment's descriptionParagraphs to make i…

    …t's usage more obvious.
    I was looking at this for a while asking myself why this is there, until I remembered it's for supporting --repeat-first-par option. So I added more detailed description for future reference.
Commits on Jan 31, 2011
  1. Increased build number to 559.

  2. Added table of contents and jump to button to object template. Closes #…

    This feature was implemented by "BloodDragon"!
  3. Method directives can now be used without being delimited from preced…

    …ing paragraph with empty line. Closes #36.
    The only requirement is that the directive is put to the start of the line, so this would work:
    	Some text
    	@param name Description
    But this wouldn't:
    	Some text @param name Description.
    This works for all directives, @param, @exception, @return and @see as well as for their variants.
  4. Implemented proper handling of methods and properties in HTML section…

    …s. Closes #60. Closes #61.
    IMPORTANT: This commit requires updating template files!
  5. Implemented `isProperty` and `isMethod` convenience properties for `G…

    …BMethodData`. Closes #58.
    This should simplify template handling as properties use somewhat different layout as pointed out by BloodDragon.
  6. Fixed unneeded template files removal after copying them over to dest…

    …ination. Closes #59.
    The problem was when a hidden file was found within a hidden directory (such as .svn with it's contents). In such case the directory was removed before processing the file and when the file was being removed, it no longer existed, so an error was reported. This is properly handled now, thanks to "BloodDragon" for pointing it out.
Commits on Jan 29, 2011
  1. Increased build number to 553.

  2. Fixed undocumented methods and properties parsing. Closes #57.

    The problem was in cases like this:
    	/** comment */
    	@property (attributes) id commentedProperty;
    	- (void)uncommentedMethod;
    After working on workaround for #43 (commit 4262bb8) forgot to reset comments when parsing methods and properties. Although above case worked properly in case of two methods (in fact there was a unit test specific for that situation and it passed), it didn't work if uncommented method (or property) followed commented property. This is correctly handled now, so it should work for both cases (added another unit test to cover above situation).
    Thanks to "BloodDragon" for pointing this one out.
  3. Increased build number to 551.

  4. Fixed "false" warnings for unknown cross references in copied comment…

    …s as mentioned in previous commit.
    Now that was really much simpler than I thought: added boolean flag to GBComment which is set to YES if the comment is copied. Then we only issue warnings if cross reference is not found and the comment is original (i.e. the flag is NO). Note that we only handle @see directives this way; any in-text local cross reference is not going to be reported as it simply won't be matched. And remote references would work the same way in both cases.
    This still leaves open the case where both, original and copied objects have members of the same name: in such case copied comment will point to destination members instead of original ones.
  5. Fixed source info for copied method comments and consequently invalid…

    … cross reference warning saying (null)@line.
    The problem was that copied GBComment didn't have source info attached, therefore the warning printed (null) instead of filename. The filename now includes both, the source comment info and destination method info in format `source@line -> method@line`, which makes it much more readable.
    Note that even with this, we get "false" warnings as all local references are simply copied over unchanged and if the destination method's parent doesn't implement them, appledoc issues a warning. This should be handled more gracefully - preferably by setting a flag on source info or comment which would prevent warnings and ignore all @see directives!
  6. Fixed warnings on undocumented objects and members handling.

    We need to handle validation after the whole object is processed because it's only at that time that we know which methods and objects will remain and which will be deleted.
  7. Increased build number to 545.

  8. Implemented optional required escaping for cross references. Closes #8.

    The issue was that user had no way of being explicit about which word should be considered cross reference and which not. Result was that any word that was also valid cross reference was converted to one. This lead to unexpected references being created from normal words - like "paragraphs" and similar.
    The user now has two choices regarding cross references: power users can provide their own cross references markers template regex, while simpler choice is to turn on explicit cross references detection. Actually this sets default markers template under the hood, so the two options should not be used together.
  9. Refactored GBCommentComponentsProvider to open up possiblity of using…

    … arbitrary cross reference regex prefix and suffix.
  10. Increased build number to 540.

  11. Fixed class methods being ignored by Xcode quick help. Closes #46.

    The problem was incorrect apple_ref - the same ref type was used for class and instance methods. Corrected by using clm for class methods and keeping instm for instance methods.
Commits on Jan 28, 2011
  1. Increased build number to 538.

  2. Added full method declaration to documentation set method token.

    In Xcode 3.2.5 quick help window, declaration doesn't end the line, next item is simply drawn right after the declaration. Tried inserting <br /> and similar, but didn't help.
  3. Fixed Xcode quick help window not displaying documentation. Closes #46.

    The problem was in doc set info.plist containing empty keys for unused values. Apparently Xcode requires keys not being present at all in such case. Haven't noticed this in documentation. Thanks to "BloodDragon" for pointing it out.
    Note that at this point only quick description and related API is shown, while parameters, declaration and the rest aren't - will need to look into that.
    IMPORTANT: template files need to be updated in order for this fix to work!
Something went wrong with that request. Please try again.