Skip to content
This repository

Typedefs, enums, functions support? #2

Open
dbfreq opened this Issue September 20, 2010 · 167 comments
Brad 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
Owner

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.

Joël Spaltenstein

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
Owner

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.

Joël Spaltenstein

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
Owner

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

Joël Spaltenstein

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
Owner

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
Owner

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.

Dylan Copeland

I would love enum support, too.

Joshua Moody

Another vote for enum support.

V1ru8
V1ru8 commented May 13, 2011

+1

Grigory Entin

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

Josh Weinberg

Make that another +1 for me.

Michael Grinich

+1

Benedikt Meurer

+1

cocoason

+1

poussain

+1

Sam Soffes
soffes commented July 04, 2011

I love this. Please do it! :)

p2k commented July 05, 2011

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

Thomas Sydorowski
tsyd commented August 19, 2011

+1

Grant J. Butler

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.

Tobias Hieta
tru commented August 25, 2011

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

James Yu

+1

Travis

+1

Travis

##+1

+1 as well

Matteo Gavagnin

+1

DougHW

I endorse this message

Justin Spahr-Summers

Love Appledoc, and this suggestion would make it even better. +1

Oliver Drobnik

+1, isn't Pilky almost done with an implementation?

Ideally I would want constants be in their own section for the documentation of a class and/or category

cccooolll

I will love it if you can support typedef and enum first,this two are too important,C functions and C++ grammar is not that important.

Tim Davies

+1

Jorge Bernal

+1

tomaz
Owner

Just an update on this: Martin Pilkington has done some work on this. Doesn't cover all aspects, but take a look at https://github.com/pilky/appledoc. Here's what he says about update:

So what has changed?

GBTokenizer
I've updated the tokenizer to not ignore whitespace. This is because the code needs to be read with formatting for the various additional info items. Each method has options allowing it to ignore or include whitespace and the existing versions of the methods default to this.

GBObjectiveCParser
I've added an additional info parsing category and 3 private properties: primaryFileObject, additionalInfoObjects, currentConstantGroup. The primaryFileObject represents the main item in the file, to which any constants will be associated. This is set in updatePrimaryFile, but basically it chooses the first class in the file, and if no class exists it chooses the first category or protocol. The other two properties are fairly self explanatory.

There is a helper called constantGroupNameFromComment: which works like sectionNameFromComment, but for constant groups.

The common parsing category has a matchAdditionalInfo method, this currently looks for any "extern", "enum" or "typedef enum" tokens.

The matchExtern method collects the tokens for the extern, searching for the name token. It think sees if the name ends in notification. If it does it hands it off to matchNotificationWithName:, otherwise it adds it to the current constant group.

The matchEnum method creates a constant group to represent the enum. Finding the name is somewhat trickier but the comments describe how it works.

Model objects
There are 3 new models, GBConstantGroupData, GBConstantData and GBNotificationData. These are pretty self explanatory. There is also a GBAdditionalInfoProvider. Classes, categories and protocols have one of these, as does the store for any project global items.

Processing
The only real change to the processing stage is the addition of the processConstantGroupBlockInString: and processOwnerBlockInString: methods

Generating
The only change to the generation stage is the templates

I'll review his changes and add them to main branch once I get some more time. In the mean time, feel free to take a look and comment in this thread. Note that his code most likely doesn't include recent bug fixes, so keep that in mind in case you come across some issues that are working in main branch.

Tobias Tom

+1 on this issue.

One more thing that might have slipped through: it would be great to be able to document blocks (like TWRequestHandler)

Thanks!

tomaz
Owner

You should be able to document block the same as any other method parameter, for example:

/** Some method.

@param handler Block description etc. etc.
*/
- (void)methodWithBlock:(void(^)(...))handler;

You can get quite creative with @param - doesn't have to be simple line - the whole text up until the end of comment or next @ directive will be taken as part of the @param description, hence you can use lists, paragraphs etc. giving you way to describe all block parameters in details. If it doesn't work for you, open a new issue to keep this one focused :)

Tobias Tom

Yes, but I was talking about something different, for example:

/**
 * The callback handler for a Twitter request.
 *
 * @param responseData The data returned by the Twitter request.
 * @param urlResponse The URL response returned by the Twitter request that includes the HTTP response codes.
 * @param error An error sending the Twitter request if it occurs.
 **/
typedef void(^TWRequestHandler)(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error);
tomaz
Owner

Aha, got it now :)

Tobias Tom

Great! Hope you like it ;o)

Do you have any ETA for 2.1?

tomaz
Owner

I'm still way too involved in other projects to take longer time for this - looks like at least to end of april. I'll continue doing smaller stuff when I get few days here and there.

David Hart

+1 for the enum and constants document! Thanks for this great tool.

tomaz
Owner
tomaz commented March 26, 2012

I've uploaded the new parsing engine to experimental branch. At the moment of this writing, only parsing is implemented, no output is generated yet! However, I'd encourage you to give it a go to see how well it recognizes your source code; your feedback is welcome so we can brush things out at this eary stage!

For all discussion on experimental branch, use (just) created appledoc Google group - this is also going to become central hub for questions so that GitHub issues is only used for feature requests and bug reports.

Tobias Tom

It's kind of hard to test when there is no output, still I'm really looking forward to this.

Thanks for your work on this!

tomaz
Owner
tomaz commented March 27, 2012

With the cmd line from readme it should spit out every recognized object. I tried to keep the output readable, so you should be able to see what was recognized and what was ignored.

Rei Vilo

+1 for C++

On #187, suggested answer was

  1. Parsing C/C++ data into GBStore

Is there some documentation available to contribute and build a C++ GBStore?

Jim R. Wilson

+1 for constants and enums, pleeeeeeeeeeeeease?

Tobias Ottenweller
tomco commented July 09, 2012

+1

Alex Gray

big ups for enums.. thought i saw a merge that maybe it got added.. but guess not?

tomaz
Owner

Parsing is already implemented on experimental branch, but it's far from doing anything useful with it. Martin Pilkington was working on this feature, don't remember to what extent he finished it - take a look at his branch (see one of my earlier comments for details).

Andres Garcia

+1

kenji21

+1

Salvatore Randazzo

+1

santthosh-inmobi

+1 for enums and constants

Till Toenshoff

+1 for functions and parameterized defines like e.g. TRACE(format,...)

Zoreslav Khimich

Another vote for typedefs (especially blocks)

Francis Labrie

+1

Jeong YunWon

+1 for function, block

Francisco Garcia

+1 for defines

Allen Hsu

+1 for enums

Michał Kluszewski

+1 for enums / constants / blocks

Davide Casarin

+1 for enums, blocks

Frank Gregor

+1 for constants / enums / functions / blocks

Fernando Fernandes

@phranck ditto! +1 for constants / enums / functions / blocks

Daniele Margutti

+1 for constants / enums / functions / blocks

Ben Collier

double +1

J.C.

+1 for constants / enums

Brennon Bortz

A hearty +1 for constants / enums / functions / blocks!

Matt Greenfield

+1

Scott Robertson
spr commented January 11, 2013

You should also be aware of NS_ENUM and NS_OPTIONS as a possible enum indicator. http://nshipster.com/ns_enum-ns_options/

Ryan C. Payne

+1

Cliff Rowley

Ah hell, I was hoping when I scrolled to the end of this 2 year old issue I'd find it had been implemented.

Ho hum, here's my +1 while I search for another doc tool to tide me over. Only reason being that I have to generate comprehensive documentation for a client, and the lack of these elements is kinda a deal breaker. I'll no doubt use appledoc for other things though.

+1

Jonathan Cichon

+1

deberle

Damn, I finally have to switch to doxygen.
I'd still love to move back to AppleDoc if enums would ever be supported.
But after 2 years I'm losing hope...

Adam Setapen

Also going to use doxygen. Can't believe enums aren't supported...

Cliff Rowley

I'm having a good time with Doxygen actually. Very comprehensive. Good output. Just about everything I need is supported, including custom Markdown content, tree navigation, etc.

Fernando Fernandes

@cliffrowley Does Doxygen look like Apple documentation? I mean, visually. (I've never used Doxygen, that's why I'm asking). Thanks.

Jim R. Wilson

If not, maybe we could develop some CSS to make it so.

Cliff Rowley

No, but tbh, it doesn't need to. I've customized the basic Doxygen styles and I'm really happy with it.

Fernando Fernandes

@cliffrowley Mm, ok. No, I totally agree with you, it does not NEED to be equal... It's just more... Visually appealing... But yes, it's a matter of style. I am thinking about switching to Doxygen too. Oh, well, that seems the way to go. Appledoc had so much potential. :'-(

Ben Stovold

+1

Mark

+1

Friedrich Pfitzmann
pfitz commented March 17, 2013

+1

Patrick B. Gibson

+1

Martijn The

+1

Steven Mok

+1 Pls support enum and const!

Ardie Hyun Hwang

+1
Really in need for documenting FOUNDATION_EXPORT NSString *const STSomething styled constants.

orschaef

+1
Not giving up the hope.

Xavi

+1

Hubert SARRET

+1

Maurício Hanika

+1

Frederic Bronner

+1

Kevin Harwood

+1

Julia Roggatz
julsh commented May 03, 2013

+1
yes please, enum support!

Matthew Bischoff

+1

Marcin Krzyzanowski
krzak commented May 15, 2013

+5

Dave Batton

+1

Felipe Cypriano
fcy commented May 17, 2013

+1

chris838

This would be so useful, not sure how I can deal without it!

-- C4 --

+1

Cory Metcalfe

+1 need constants documented

If there were a way to trigger a comment block to get parsed into a chunk of markdown (without requiring a method declaration to not be ignored), I could mock in comments around my constant declarations, following an @name/pragma group, which would suit my purposes.

tomaz
Owner
tomaz commented May 26, 2013

@coryallegory At present this is only supported for "static documents" - http://gentlebytes.com/appledoc-docs-examples-documents/ but the code would need a patch to make it generate other references list and allow cross referencing.

Adam Setapen

@tomaz Nice to see you. I love appledoc, but many of us can't use it without this critical functionality.

3 years have passed since this issue was opened. I remember reading a year or two back that you were "actively working" on this feature. Care to comment?

tomaz
Owner
tomaz commented May 28, 2013

You're right - I created this issue after releasing 2.0. I already anticipated these features, but just never got to it. Then current master became quite buggy and regression prone with time, so I finally decided to make major redesign to make it more future proof and bring in most requested featuers. So about a year ago I started work on 3.0 which includes most of this functionality (currently functions aren't supported yet). While I'm still excited about it, unfortunately wasn't able to attend the code for past several months due to my work.

I am slowly growing into idea of reaching out for help - perhaps this issue is not a bad start given it's frequency. I think current stuff is well prepared and a lot has already been done. With few devs each working on specific part, I think it shouldn't take too long to bring some usable results. What do you (all) think?

Reid Ellis
rae commented May 30, 2013

Good idea!

Adam Setapen

It's definitely a great idea. The flood of +1's shows you how much of a need there is for appledoc to work perfectly, and I'd be glad to help make this feature request a reality.

Javier Soto

+1

robvdveer
Collaborator

+1

Mark Aufflick

It occurs to me that auto-documenting enums becomes a lot easier to parse if you limit support to NS_ENUM() which has a lot more regular syntax than the various ways people like to use enum/typedef.

Just a thought in case @tomaz ever scrolls to the bottom :)

Update: Lol at myself for not noticing that @spr already suggested this...

tomaz
Owner
tomaz commented July 24, 2013

Haha, I do scroll to the bottom, for every new comment :) 3.0 on experimental branch already has this implemented in parser (or at least I think it does, but if not, it was my intention to implement it this way :)

robvdveer
Collaborator

Just a little update here as i'm current working on getting the NS_ENUM thing tackeled, which i want to work for my project (and the community). The parser bit is done, after the break i'll start working on the generator. Basically i'm just reading the enum definition, and the named constants, adding them to the list. To avoid complexity with grouping, i'll be adding another section to the docset 'Constants' to list all the enums. I now Apple folds these into the class documentation, but it do not mind this as long as the hyperlinking works.

If anybody has a better idea or a reason why i should not continue this approach, let em speak now..

tomaz
Owner
tomaz commented July 25, 2013

I think it's valid starting point. But if anyone has better suggestion (while keeping it simple), let it out...

Mark Aufflick

I actually like the idea of them being separate. I've always found it odd that something so important is buried right down at the bottom of a class. And in a way an enum is a definition of a new type rather than just some part of the class definition.

@robvdveer are those changes on the master of your fork?

robvdveer
Collaborator
robvdveer
Collaborator

I nailed the enum definition. Not bad for about 8 hours of coding. Lots of tweaks and edge cases to inspect.

(apologies for the large screenshot)

organizer_-_documentation_and_goodstuff xcworkspace__gseasingfunction h_and_appledoc xcworkspace__gbcommentcomponentsprovider m

I you want, you can check out my fork of the master branch (https://github.com/robvdveer/appledoc)

Edit: some more details:

  • typedef enum { .... } [name]; is the only currently supported notation. Other types may/will crash
  • not documenting the typedef will trigger a warning
  • not documenting a constant will not trigger a warning
  • even undocumented enums will appear in the docs (needs a switch?)
  • available since for a constant does not work
  • cross referencing from/to enum definitions from comments work
  • automatic cross references to the same dcument are disabled (to stop linking to itself)
  • availability/see also works
  • templates for html and docset have been modfied
  • css has been expanded, properties copy from Apple css
  • refactoring/naming still needed
  • no unittests
  • committed version contains changes to build scheme settings (commandline params) and build number.
robvdveer
Collaborator

I forgot to mention that i intend to fix the notation requirement to support this type of enum only, since that is what Apple suggests

typedef NS_ENUM(NSUInteger, ShapeType) {
kCircle,
kRectangle,
kOblateSpheroid
};
tomaz
Owner
tomaz commented July 25, 2013

Cool! An answer to your previous comment There was no need to over-engineer this stuff and wait 2 years...: regressions. Every new contribution breaks some other existing feature, unexpectedly. Not by fault of contributors of course, it's combination of hacked codebase I produced. I wanted to make the platform more stable so new features are more easily added. So the idea wasn't over-engineering, but rather minimizing support costs :)

robvdveer
Collaborator
robvdveer
Collaborator

Today's progress on the enum stuff:

  • typedef enum { .... } [name]; is no longer supported. I did some digging and NS_ENUM is indeed smarter (See http://nshipster.com/ns_enum-ns_options/). I needed to change the docset token generator for them to properly recognize (it is now /apple_ref/c/tdef/name and /apple_ref/c/econst/name, instead of the /occ/ tag. But anyway, both the quickhelp for NS_ENUM, NS_OPTIONS and their items definitions properly shows up.
  • i've added a compiler warning for items that are still in the typedef enum { } [name] style, so you know they won't be documented.
  • added a few features like 'availability' and 'declaration' to the quickhelp popups to give 'em a little more meat (see screenshot)
  • not documenting a constant will now trigger a warning
  • there's still a little issue when you don't document all a constant, it'll use the documentation from the typedef (??)
  • templates are changed again

goodstuff xcworkspace__bounceviewcontroller m

To install this version, just 'git' it from the url below and 'sudo ./install-script.sh' as you do with a normal version update. Just note that the templates have changed so you need to copy/merge them.

If you want to test, check out my fork at https://github.com/robvdveer/appledoc.git

Mark Aufflick
Dominik Hádl

+1

Steven Mok

@robvdveer really cool! Thanks for your hard working!

Dominik Hádl

@robvdveer Great work! I've noticed a small bug.
In order to support iOS5 I have a #ifdef on the NS_ENUM - like this:

#ifndef NS_ENUM
#define NS_ENUM(_type, _name) enum _name : _type _name; enum _name : _type
#endif

And this gives me a warning about unsupported enum type.

robvdveer
Collaborator

I'll fix that asap, i already know he cause. It's actually complaining on an unsupported typedef but i'll fix it anyway.

tomaz
Owner
tomaz commented July 29, 2013

FYI: I tagged latest release, including @robvdveer additions with v2.2.

Franken Zeng
fpzeng commented July 29, 2013

+1

Hubert SARRET

I can't seem to make documenting enum to work, anything special to do ?
I just git pulled and sudo sh install-appledoc.sh (and of course updating my doc as usual)

tomaz
Owner
tomaz commented July 29, 2013

Make sure you use updated template files (although install script should copy them, but make sure you're not using --templates switch or otherwise use different templates), then only NS_ENUM and NS_OPTIONS style is supported. With that, it should create "Constant References" section in index where all constants are listed. Each one is represented by its own HTML file.

Hubert SARRET

sudo sh install-appledoc.sh -t default did the trick, thanks for helping @tomaz

robvdveer
Collaborator

I might be able to tackle or typdefs (typedef struct or typedef function block) but the syntax gets rather tricky (documenting params etc). I'll let you know when i make some progress. Perhaps its enough just to crossref the definition?

Dominik Hádl

Btw, are you planning to look into documenting C functions and #define macros? :)

robvdveer
Collaborator
Dominik Hádl

Well, the reason I was talking about C is, that I have for each macro a C function which returns string (char) with the name of the enum - basically enum->string conversion. Something like this:

static inline const char *stringFromDDRedeemCodeStatus(DDRedeemCodeStatus codeStatus)
{
    static const char *strings[] = {"DDRedeemCodeStatusValid", "DDRedeemCodeStatusInvalid", "DDRedeemCodeStatusBlacklisted", "DDRedeemCodeStatusForged"};
    return strings[codeStatus];
}

And it would be nice if I could cross-reference to it and have it in the documentation.

Btw. What about #define macros? Because I have all the setup of my class in the header file using define macros. And that would be also very nice to document :)

tomaz
Owner

There will always be edge cases, I think adding support for "80%" should be enough...

BTY (and not trying to divert the topic, although this would probably eliminate the need to document C functions in your case :) you could streamline your code a bit using C preprocessor to convert your constants into strings (as long as result string is exactly the same as your statuses):

#define STRING_FROM_VAR(var) #var

NSLog(@"%s", STRING_FROM_VAR(DDRedeemCodeStatusValid));
NSLog(@"%s", STRING_FROM_VAR(DDRedeedCodeStatusInvalid));

This would actually print out the codes as strings. You could also convert them to NSString if that's how you'd need it:

NSString *string = [NSString stringWithCString:STRING_FROM_VAR(DDRedeemCodeStatusValid) encoding: NSASCIIStringEncoding];
Dominik Hádl

Yeah, I know I can stringify it with preprocessor and as you said, it probably is the best solution, thanks. I just always want more and more and more features and sometimes it is too much :D

robvdveer
Collaborator
Marcin Krzyzanowski

ok now... how to use it? I get lot fo warning that my NS_ENUM is undocumented but can't find if I need to do some special magic to document it.

Marcin Krzyzanowski

warning: DEPRECATED_ATTRIBUTE is not documented

MethodBasic DEPRECATED_ATTRIBUTE = 0

how to document this attribute? thanks

robvdveer
Collaborator
Thongchai Kolyutsakul

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? :/

Edit: OK, it seems to already work. I was expecting Constant References section to appear in my class doc page that I declare the enum, but it actually in the index page. Duh. Closed.

robvdveer
Collaborator
TheRock1987

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
Collaborator

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.

Jeffrey Wear wearhere referenced this issue in inkling/Subliminal September 09, 2013
Open

Update Subliminal to use appledoc 2.2. #71

Adam Gluck

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.

Steffen Itterheim

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

OGWEntityCategoryOptionNeedsUpdate = ( 1 < < 0 ),

robvdveer
Collaborator
Paul Peelen

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

Doug Richardson

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

robvdveer
Collaborator
J to the A

+80

We need function documentation for great justice!

Brennon Bortz

+1

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.