Support blocks #391

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

Projects

None yet

4 participants

@IronSight87
Contributor

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

Short answer: yes, i got it planned (i don't think tomaz would object)

Longer answer: to be able to parse this correctly, a lot of additional code is necessary. It may not be feasible since xcode 5 is around the corner and who-knows-what they've got planned for it. I'm using blcks quite frequent myself (coming from C# lambda's) and a little documenation is always welcome.

http://simplicate.weebly.com

On Sun, Aug 11, 2013 at 12:00 PM, tomaz notifications@github.com wrote:

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.

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

@IronSight87
Contributor

Thank you to you both :)

@tomaz

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

@IronSight87
Contributor

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

@robvdveer
Collaborator

It isn't supported yet. No point trying. You can only add a custom document with the documentation or add extra comments to the method to explain the parameters. @param etc will not work on that level

Op 12 aug. 2013 om 12:11 heeft TheRock1987 notifications@github.com het volgende geschreven:

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


Reply to this email directly or view it on GitHub.

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

@IronSight87
Contributor

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

extern NSString *SomeNotification;

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

Not at this point... - see #2

@IronSight87
Contributor

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