Missing category docs on custom classes #117

epologee opened this Issue Jun 27, 2011 · 10 comments


None yet
3 participants

My generated documentation is missing a few categories of my project. I don't understand why they're omitted. The categories are in files like Chain+Serialization (.h/.m) and Shackle+Serialization (.h/.m). The classes they extend are included and generated correctly.

I first thought it had something to do with the + sign in the file names, but there are other categories in there that are parsed. Then I noticed that all listed items in the 'Category References' of the hierarchy.html file are categories on Cocoa Touch framework classes. None of my categories on custom classes are listed: screenshot. I'm currently missing three categories.

Would you have a clue of how to fix this? Let me know if you need any additional info. Cheers, EP.


tomaz commented Jun 27, 2011

If these are categories for classes that are "known" to appledoc (i.e. they also get parsed during the same session), then the documentation is merged to the classes by default. This is how Apple seems to be doing, but you can override it with --merge-categories or --no-merge-categories as well as refine how the stuff should be merged, described briefly here.

I'm closing the issue, but feel free to reopen it if this is a genuine bug.

tomaz closed this Jun 27, 2011

You're totally right, I didn't notice they had been merged! Sorry!


tomaz commented Jun 27, 2011

Cool, would love to see more of these "quick-fix" issues :)

I'd like a reopen on this, actually, because I believe the behavior the OP is reporting is technically a bug.

  1. If I have a custom class with "top-level" documentation
  2. If the class has a category with "top-level" documentation
  3. If I have --merge-categories enabled (which is the behavior I want, a "merged" category)

Expected: The top-level documentation in 1) and 2) are merged into the single documentation for the class.

Actual: The top-level documentation in 2) is ignored. Not merged with some other documentation. Completely thrown away.


tomaz commented Feb 11, 2012

Could you provide example that would demonstrate the issue? Either post here if it's short, gist it or send it to my email (in readme file) so I can give it a go.

Put together a sample project at

  1. Build the attached project, with appledoc in /usr/local/bin (or edit the script accordingly to point to the path). I've tested 2.0.4 - yesterday's master branch with the same behavior.
  2. Run. The documentation will build and install into XCode.
  3. Note that the doc defined in ArbitraryClass.h appears, but not the doc from ArbitraryClass+Category.h. I would think that the reasonable interpretation of "merge categories" would be that both strings would appear in the class documentation somewhere, but in fact they are mutually exclusive.

tomaz commented Feb 12, 2012

Thanks, downloading right now. Will update with my findings.

@tomaz tomaz added a commit that referenced this issue Feb 23, 2012

@tomaz tomaz When merging categories to classes, their comment is also merged. Add…
…resses #117.

This is on by default, but can be controlled through `--merge-category-comment` cmd line switch.

tomaz commented Feb 23, 2012

Just added this functionality. Note that it currently simply appends category comment to the end of current comment text (it adds a new line in between). If there are multiple categories, the order is undefined (most likely sorted by file names). This is on by default, but you can disable it through cmd line switch in case it doesn't work or you don't want it.

Thanks! This fixed my issue.


tomaz commented Feb 29, 2012

Glad to hear that! It took me a while before I understood what the issue was, I never commented categories when I used merging, so it didn't occur to me to add this :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment