Typedefs, enums, functions support?

[b-gibbs]

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

[tomaz]

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

[amyworrall]

I'd like this as well. Just the ability to list enums, along with a comment per item, would be beneficial.

[spalte]

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

[tomaz]

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.

[spalte]

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

[tomaz]

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).

[spalte]

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.

[tomaz]

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.

[amyworrall]

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.

[tomaz]

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.

[dylancopeland]

I would love enum support, too.

[jmoody]

Another vote for enum support.

[V1ru8]

+1

[grigorye]

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.

[tomaz]

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.

[jweinberg]

Make that another +1 for me.

[grinich]

+1

[bmeurer]

+1

[wsinnema]

+1

[poussain]

+1

[soffes]

I love this. Please do it! :)

[p2k]

+1 this is about the only feature that's missing for me; it would make appledoc my number one doc tool.

[tsyd]

+1

[grantjbutler]

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.

[tru]

+1 here too. Love everything with appledoc, but I really need this. Is there any known workarounds, write custom documentation or?

[jamesyu]

+1

[trawor]

+1

[trawor]

##+1

[robvdveer]

-t default does not overwrite existing templates. Go to ~/.appledoc and remove that folder. Then install with -t once more.

—

http://simplicate.weebly.com

On Wed, Aug 21, 2013 at 6:23 AM, Thongchai Kolyutsakul
notifications@github.com wrote:

I just did git clone git://github.com/tomaz/appledoc.git, I see the code handles parsing typedef enum but when I generate the doc it doesn't show the constant section. And I still get "Unsupported typedef enum at Class.h". I tried sudo sh install-appledoc.sh -t default and NS_ENUM but still doesn't work. Did I miss something? :/

Reply to this email directly or view it on GitHub:
#2 (comment)

[IronSight87]

I would also expect that the constant section will appear in the class doc page, where the enum is declared (like Apple does it).
Could this be changed?

Thanks!

[robvdveer]

Grouping the constant definition with the class is not a priority. The generated hyperlinks and search are fully functional the way it is. If you read the entire issue (yes, i know it is a long thread), you will see that I have implemented this NS_ENUM feature with as little impact to existing systems as possible. Integrating them to the existing class documentation would be a major overhaul, probably only in release 3. All the work involved may not be feasible because we don't know what Xcode 5 brings us.

[AdamGluck]

Thanks so much for an awesome and easy to use tool!

The only issue is that I cannot get NS_ENUM to be picked up in the documentation.

  /*!
     @enum SterlingRequestServerResponse enum
     @abstract delegate method that handles a server response.
  */
     typedef NS_ENUM(NSInteger, SterlingRequestServerResponse) {
          /*! the request failed, something was passed incorrectly or some other error occured not related to connectivity. Make sure you have requested all permissions and that  */
          SterlingRequestFailed,
          /*! No response from the server, this likely means there is an internet connectivity issue on the user end */
          SterlingRequestNoResponse,
          /*! sterlingUserLogin method succeeded */
          SterlingLoginSucceded,
         /*! This returns when the server is still processing a request, currently not used */
         SterlingRequestProcessing,
         /*! Invitations were sent to user, currently not used publically */
         SterlingInvitationSucceeded,
   };

No matter where I place this in my code I cannot get the parser to pick it up. Right now it is in an @protocol.

This is my runtime script

 if [ ${CONFIGURATION} == "Debug" ]; then
 /usr/bin/appledoc \
 --project-name ${PRODUCT_NAME} \
 --project-company "ProjectCompany" \
 --company-id "com.CompanyName" \
 --output ${PRODUCT_NAME}Docs \
 --keep-undocumented-objects \
 --keep-undocumented-members \
 --keep-intermediate-files \
 --no-install-docset \
 --ignore .m \
 --no-repeat-first-par \
 --no-warn-invalid-crossref \
 --exit-threshold 2 \
 ${PROJECT_DIR}/${PRODUCT_NAME}
 fi;

I've deleted the whole installation (usr/local/bin/appledoc and ~/.appledoc) and re-installed it with sudo sh install-appledoc.sh -t default and git clone https://github.com/tomaz/appledoc.git.

Any advice would be appreciated! I'm using XCode 5.

[LearnCocos2D]

Just a minor thing, the constants page for an enum adds extra spaces around brackets and between the << bitshift operator:

OGWEntityCategoryOptionNeedsUpdate = ( 1 < < 0 ),

[robvdveer]

This is because the tokenizer does not see << as one, but two, tokens.

—
http://simplicate.weebly.com

On Tue, Oct 22, 2013 at 6:55 PM, Steffen Itterheim
notifications@github.com wrote:

Just a minor thing, the constants page for an enum adds extra spaces around brackets and between the << bitshift operator:

OGWEntityCategoryOptionNeedsUpdate = ( 1 < < 0 ),

Reply to this email directly or view it on GitHub:
#2 (comment)

[ppeelen]

@AdamGluck Did you ever solve your issue? I have the exact same problem. Tried Rob's fork as well.. complete new install and removed the ~/.appledoc but just can't get it to pick up either typedef enum or NS_ENUM into the documentation. Using the same params as you are.

[drichardson]

I see that some progress has been made on the enum front. Any news on functions?

[robvdveer]

I have not found the time to work on this, i am sorry.—
Sent from Mailbox for iPad

On Fri, Jan 17, 2014 at 12:48 AM, Doug Richardson
notifications@github.com wrote:

I see that some progress has been made on the enum front. Any news on functions?

Reply to this email directly or view it on GitHub:
#2 (comment)

[freysie]

+80

We need function documentation for great justice!

[brennon]

Wow. What better reason do you need than for justice??

Sent from my iPhone

On Jan 30, 2014, at 8:21 PM, Jakob Alminde notifications@github.com wrote:

+80

We need function documentation for great justice!

—
Reply to this email directly or view it on GitHub.

[dirtyhenry]

+1.

[migrant]

+1

[cloutiertyler]

+1

[alexmedearis]

+1 vote for C-functions and #define C-macros

[alexwald]

+1

[blackivory86]

First: Thanks for adding NS_ENUM support!

We're still runnning into an issue when mentioning enum-values in the documentation comments of enum values. In that case we can not get appledoc to output documentation:

Not working:

typedef NS_ENUM(NSInteger, EnumOne)
{
   /** Test-value of EnumOne. Check the EnumTwoValue for details. */
   EnumOneValue
};

typedef NS_ENUM(NSInteger, EnumTwo)
{
   /** Test-value of EnumTwo*/
   EnumTwoValue
};

EnumTwoValue and EnumOne/EnumTwo need to be removed from the comments to make the doc compile

Working:

typedef NS_ENUM(NSInteger, EnumOne)
{
   /** Test-value of Enum-one. Check the  for details. */
   EnumOneValue
};

typedef NS_ENUM(NSInteger, EnumTwo)
{
   /** Test-value of enum-two You can call [TestClass testMethod] to get further details */
   EnumTwoValue
};

/**
 Test-Class
 */
@interface TestClass : NSObject
/** Test-Method */
- (void)testMethod;
@end

References to classes and methods seems to work

[LearnCocos2D]

+1 for documenting functions (and macros, typedefs, structs)

[alanma]

+1 for documenting macros, typedefs, and structs.

[tomaz]

Stealing away this thread being the most frequented one: I'm searching for collaborators on appledoc, see blog post at http://gentlebytes.com/blog/2015/11/02/appledoc-contributors-needed/ and if interested, contact me!

[suxinde2009]

hi, is NS_ENUM be suppored now?

[tomaz]

For a long time ;)