appledoc
appledoc copied to clipboard
tomaz
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
Currently these are not supported by appledoc. Doxygen does pick up the documentation and prepare xml, but appledoc doesn't parse these parts. I'm documenting enums as a list inside the documentation of method or object that uses them.
I'm considering this feature for v2, but it's not one of the primary goals. Will look into it once the rest of the functionalities is stable. Should be relatively simple to add codewise, but would require some though to do it the right way.
Tomaz
I'd like this as well. Just the ability to list enums, along with a comment per item, would be beneficial.
And one more vote! With the added request to be able to document notifications as well.
Nice work Tomaz! I have just started using AppleDoc, and so far it looks very promising!
Joël
This is indeed one of the most requested features together with #7. Any appledoc feature is implemented so that it supports or mimics Apple's documentation, so this should include enumerations (or constants, so this would also count notifications). Need to find a way to link these into the rest of the documentation in a nice and logical way. Haven't payed a lot of attention how Apple does it, but I think they just list all constants in a single file and link to them from classes docs. Although I think they also list notifications related to a specific class in the TOC.
Notifications tend to be included in the same file as the class that sends them under a "Notifications" heading. Constants, such as enums, that are really related to a specific class tend to be included in the class file under a "Constants" header. The NSWindow class reference docs are a good example of a very complicated documentation file. Other data types and structs tend to be included is a separate Data Types Reference file. I also have some C objects that I use like Core Foundation (ex. CFString) objects that have a straight C API, and I would love to be able to document these classes using appledoc.
Again, thanks for an awesome documentation tool, Joël
Though so. This would require an option to link certain items with specific class (or category/protocol). It would also require specifying whether a constant is a notification or something else. Perhaps something along the lines:
/** @notification ClassName GroupName Description */
NSString *NotificationName = "SomeName";
/** @constant (or @enum) ClassName GroupName Description */
enum {
/** Description */
Value1,
/** Description */
Value2,
};
typedef NSUInteger ConstantType;
/** @constant ClassName GroupName Description */
#define / whatever
If an item represents some generic constant or notification, it could have ClassName omitted and it would be placed in a common file referenced from index.html. Judging from NSWindow example, constants are also grouped and each group can have a title and description attached (for example Window Levels or Display Device—Descriptions).
Cross references to/from constants could be handled the same way as now - if any word is recognized, it's converted to crossref (of course explicit refs should be used here too).
I like it, and that approach would also work for functions that would be nice to have grouped together. I'm not quite sure how you plan on detecting if there is a ClassName and GroupName or not. Would you just see if the next word is in the list on known ClassNames and GroupNames? How would you know if the user wanted to define a new GroupName?
The concept of a GroupName might also be useful for other nice-to-have but not critical features like grouping several categories together in a single file. In particular I am thinking of categories on NSValue to work with new struct types. For example valueWithPoint: is defined in NSValue (NSValueGeometryExtensions) in NSGeometry.h and valueWithRange: is defined in NSValue (NSValueRangeExtensions) in NSRange.h yet they are documented in the same file. Similarly, I have a categories on NSValue for my own types that are defined is several different headers, and while it would not be the end of the world if each category appeared in it's own file, being able to define a ClassName GroupName might make it possible to have them all in the same file.
Didn't give much attention to these details, just quickly wrote them to open a discussion and get various suggesions and as future reference. One possible implementation would be to have first word as reference to the class followed by group name enclosed in some markers (quotes for example), followed by free description with the same rules as any appledoc comment. Or to require description starting in next line.
As for grouping categories, I've opened another issue - see #65.
I like the idea of groupname. Perhaps you could omit the classname in the enum's comments, and then in any class file where you want those constants to show you do @showconstants
Either way, this looks good.
Yes, that would be another possibility. It's actually a good one as it would allow including the same set of constants in multiple classes.
First of all, Appledoc is a really great peace of software. Thanks for your work!
I would like to get support for functions, enums and constants (NSStrings). I would prefer if there was a way to document such things without some @tag, reference or whatever. I really don't want to put such a tag in documentation for every symbol.
The kind of the documented entity should be picked from the source code, so no tag should be required just for generating documentation. But tags would be needed for mapping the documentation to other symbols.
+1 this is about the only feature that's missing for me; it would make appledoc my number one doc tool.
This is a must for me. I just switched from headerdoc to appledoc, and because this is missing, I may be forced to switch back, which is something I don't want to do; I prefer appledoc over headerdoc.
+1 here too. Love everything with appledoc, but I really need this. Is there any known workarounds, write custom documentation or?
