Skip to content

Support blocks #391

Open
TheRock1987 opened this Issue Aug 11, 2013 · 12 comments

4 participants

@TheRock1987

Hi,

is it planned to support the documentation of blocks?
In my opinion there are two possibilities:

  1. like TWRequestHandler as a constant (see http://developer.apple.com/library/ios/documentation/Twitter/Reference/TWRequestClassRef/Reference/Reference.html#//apple_ref/c/tdef/TWRequestHandler)

  2. like loadAchievementsWithCompletionHandler in GKArchievments as an indented sub parameter (see http://developer.apple.com/library/ios/documentation/GameKit/Reference/GKAchievement_Ref/Reference/Reference.html#//apple_ref/occ/clm/GKAchievement/loadAchievementsWithCompletionHandler:)

Thanks!

@tomaz
Owner
tomaz commented Aug 11, 2013

In a way it's possible to use either solution now (although second one may confuse appledoc as some block definitions can get quite complex). Parameter description can span multiple lines, so you can describe parameters for the block like this:

@param block block description

     - *param1* param description
     - *param2* param description

But cross linking won't work like it does on your first example. At present cross referencing on declaration line is not supported.

@robvdveer
Collaborator
@TheRock1987

Thank you to you both :)

@tomaz

1.

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

2.

Performs the request and calls the specified handler when done.
@param handler The handler to call when the request is done.

   - *param1* responseData The data returned by the Twitter request.
   - *param2* urlResponse The URL response returned by the Twitter request that includes the HTTP response codes.
   - *param3* error An error identifier.
@discussion I don't know ...

right?

@tomaz
Owner
tomaz commented Aug 11, 2013

That should do it.

@TheRock1987

I tried the first solution with @constant, but it does not work.
Any ideas?

@robvdveer
Collaborator
@tomaz
Owner
tomaz commented Aug 12, 2013

Probably we misunderstood - as @robvdveer block parameters aren't parsed. But you can kind-of fake it like I suggested. Here's more complete example:

/** Description of the method.

@param completionHandler A block to be called when the download is completed.

- *achievements*: An array of achievement objects that represents all progress reported to Game Center for the local player. If an error occurred, this parameter may be non-nil, in which case the array holds whatever achievement information Game Kit was able to fetch.
- *error*: If an error occurred, this object describes the error. If the operation completed successfully, this value is nil.
*/
+ (void)loadAchievementsWithCompletionHandler:(void (^)(NSArray *achievements, NSError *error))completionHandler;

You won't get exact results as in Apple docs, but you can experiment with various layouts, for example with definition lists that discount supports.

@TheRock1987

Thank you for your fast answer :)
One last question: Some constants like enums can be documented. What about Notifications:

extern NSString *SomeNotification;

@TheRock1987 TheRock1987 reopened this Aug 12, 2013
@tomaz
Owner
tomaz commented Aug 12, 2013

Not at this point... - see #2

@TheRock1987

It may not be feasible since xcode 5 is around the corner and who-knows-what they've got planned for it

The new features of Xcode 5 are already known - Click me

@tomaz
Owner
tomaz commented Sep 18, 2013

They are know since WWDC, mentioned publicly on website too, so I guess it's notpart of NDA, but not everyone had the chance to experiment with them. Plus at the time being we didn't know where they're taking it. For me (and am sure @robvdveer was thinking the same) the relevant feature is handling of documentation - it started a while ago with clang support for parsing code documentation and now Xcode takes it another step and uses it in quick help and code sense. Frankly i didn't check to what extent the docs are parsed, but what is important is that Apple is stepping into this direction (finally :) With this the need of appledoc becomes somewhat less important - one major job (quick help) is already taken care of, so what remains is html and docset.

@kremens
kremens commented Sep 22, 2013

"With this the need of appledoc becomes somewhat less important - one major job (quick help) is already taken care of, so what remains is html and docset"

Now that I'm using XCode 5, I tend to disagree! Apple has actually made the documentation viewer worse. You can have tabs, but no more Table of Contents! And you can add your own documentation, but it won't be added to a docset. Really?

Appledoc is and was a valuable thing. I hope you'll continue improving it, and most of all, documenting it. At this point, it certainly works well enough to be usable. But doing so is quite painful, as the documentation is poor (official docs don't exist...). Ironic, as it's a documentation program! Piecing together little bits of information from multiple, incomplete tutorials is a drag...

Short story - Appledoc is still useful! All it needs is documentation.

@tomaz tomaz added the Feature label May 16, 2014
@tomaz tomaz added this to the 3.0 milestone May 16, 2014
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.