Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Typedefs, enums, functions support? #2

Open
b-gibbs opened this Issue Sep 21, 2010 · 176 comments

Comments

Projects
None yet
@b-gibbs
Copy link

b-gibbs commented Sep 21, 2010

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

This comment has been minimized.

Copy link
Owner

tomaz commented Sep 21, 2010

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

This comment has been minimized.

Copy link

amyworrall commented Feb 8, 2011

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

@spalte

This comment has been minimized.

Copy link

spalte commented Feb 8, 2011

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 comment has been minimized.

Copy link
Owner

tomaz commented Feb 8, 2011

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

This comment has been minimized.

Copy link

spalte commented Feb 8, 2011

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

This comment has been minimized.

Copy link
Owner

tomaz commented Feb 9, 2011

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

This comment has been minimized.

Copy link

spalte commented Feb 9, 2011

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

This comment has been minimized.

Copy link
Owner

tomaz commented Feb 9, 2011

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

This comment has been minimized.

Copy link

amyworrall commented Feb 9, 2011

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

This comment has been minimized.

Copy link
Owner

tomaz commented Feb 9, 2011

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

This comment has been minimized.

Copy link

dylancopeland commented Feb 21, 2011

I would love enum support, too.

@jmoody

This comment has been minimized.

Copy link

jmoody commented Mar 25, 2011

Another vote for enum support.

@V1ru8

This comment has been minimized.

Copy link

V1ru8 commented May 13, 2011

+1

@grigorye

This comment has been minimized.

Copy link

grigorye commented May 22, 2011

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

This comment has been minimized.

Copy link
Owner

tomaz commented May 23, 2011

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

This comment has been minimized.

Copy link

jweinberg commented May 23, 2011

Make that another +1 for me.

@grinich

This comment has been minimized.

Copy link

grinich commented Jun 17, 2011

+1

3 similar comments
@bmeurer

This comment has been minimized.

Copy link

bmeurer commented Jul 3, 2011

+1

@wsinnema

This comment has been minimized.

Copy link

wsinnema commented Jul 3, 2011

+1

@poussain

This comment has been minimized.

Copy link

poussain commented Jul 4, 2011

+1

@soffes

This comment has been minimized.

Copy link

soffes commented Jul 4, 2011

I love this. Please do it! :)

@p2k

This comment has been minimized.

Copy link

p2k commented Jul 5, 2011

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

@tsyd

This comment has been minimized.

Copy link

tsyd commented Aug 19, 2011

+1

@grantjbutler

This comment has been minimized.

Copy link

grantjbutler commented Aug 22, 2011

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

This comment has been minimized.

Copy link

tru commented Aug 25, 2011

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

@jamesyu

This comment has been minimized.

Copy link

jamesyu commented Oct 30, 2011

+1

1 similar comment
@trawor

This comment has been minimized.

Copy link

trawor commented Nov 9, 2011

+1

@trawor

This comment has been minimized.

Copy link

trawor commented Nov 9, 2011

##+1

@robvdveer

This comment has been minimized.

Copy link
Collaborator

robvdveer commented Aug 21, 2013

-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

This comment has been minimized.

Copy link
Contributor

IronSight87 commented Aug 24, 2013

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

This comment has been minimized.

Copy link
Collaborator

robvdveer commented Aug 24, 2013

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

This comment has been minimized.

Copy link

AdamGluck commented Oct 13, 2013

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

This comment has been minimized.

Copy link

LearnCocos2D commented Oct 22, 2013

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 comment has been minimized.

Copy link
Collaborator

robvdveer commented Oct 22, 2013

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

This comment has been minimized.

Copy link

ppeelen commented Dec 16, 2013

@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

This comment has been minimized.

Copy link

drichardson commented Jan 16, 2014

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

@robvdveer

This comment has been minimized.

Copy link
Collaborator

robvdveer commented Jan 17, 2014

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)

@alminde

This comment has been minimized.

Copy link

alminde commented Jan 31, 2014

+80

We need function documentation for great justice!

@brennon

This comment has been minimized.

Copy link

brennon commented Jan 31, 2014

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

This comment has been minimized.

Copy link

dirtyhenry commented Feb 19, 2014

+1.

@migrant

This comment has been minimized.

Copy link

migrant commented Apr 17, 2014

+1

1 similar comment
@cloutiertyler

This comment has been minimized.

Copy link

cloutiertyler commented Apr 29, 2014

+1

@alexmedearis

This comment has been minimized.

Copy link

alexmedearis commented Jun 20, 2014

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

@alexwald

This comment has been minimized.

Copy link

alexwald commented Aug 5, 2014

+1

@blackivory86

This comment has been minimized.

Copy link

blackivory86 commented Jan 8, 2015

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

This comment has been minimized.

Copy link

LearnCocos2D commented May 2, 2015

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

@alanma

This comment has been minimized.

Copy link

alanma commented Jun 4, 2015

+1 for documenting macros, typedefs, and structs.

@tomaz

This comment has been minimized.

Copy link
Owner

tomaz commented Nov 2, 2015

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

This comment has been minimized.

Copy link

suxinde2009 commented Jun 26, 2017

hi, is NS_ENUM be suppored now?

@tomaz

This comment has been minimized.

Copy link
Owner

tomaz commented Jun 26, 2017

For a long time ;)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.