Xcode 8b2 Documentation Tags Broken (aka @method, @see, etc)

Sorry, not a question, more of a comment for others struggling with same and a tutorial for those wondering how "command-click documention" works (or did in Xcode piror to 8b2)


It appears that in Xcode 8 the documentation "@" directives or documentation section tags are broken.


These are the tags with the @ in comments that the editor will look for in a comment immediately preceeding a method defintion or class definition. They give you the ablity to hold the command key down (cursor turns into a bold "?") and click something to see the documentation on that something in all the GUI glory of Apple's style from their Cocoa documentation but for your own code. Same works for method, functions, variables, classes, yada yada with some variations (a variable does not use @method for example)


For a specific example, put this comment above one of your methods and then anywhere in your compiled code (aka parsed and compilable) command-click on the method name you chose. You will see this documentation displayed in Xcode 7. In Xcode 8, you won't. Huge problem.


/!

@method - (DataTaskWithURLBlock) dataTaskWithURLBlock:selector

@abstract returns a glorified function pointer to a block.

@discussion the block returned will generically spin up a thread to parse data as dictated by the pseudoglobal "selector"

Apple Blocks are usuallly rife with side effects of unintentional semi-global variable access within the routines

where they declared within parameters of Cocoa library functions. This method ensures that all variable access

within the Apple Block is tightly controlled to avoid such side effects which impact app stablity.

Single biggest problem with Apple Blocks is that they depend upon semi-globals for data exchange with the

core code.

Status: development - Wm. Cerniuk - 3/26/16

@see CDBlocks/CDBlocks.h to understand the block encapsulation design pattern

@param selector a pseudo-global to the block that contains the parse method selector responsible for

understanding the data returned from the call.

@return a pseudo-function pointer to the Apple Block code

*/

- (DataTaskWithURLBlock) dataTaskWithURLBlock : (SEL) selector {

In this case, note the @method, @abstract, @discussion, @see, @param, @return. These are all comment section tags that are parsed by the Apple parser and then brought to life in the window that shows when in this example I click in my code on dataTaskWithURLBlock either directly below the comment or where dataTaskWithURLBlock was used in the code elsewhere.


In some WWDC 2016 video I can't find now where they are going across all of the Xcode 8 features, the presenter shows some command key for inserting a documentation comment block. For me this is a huge "yawn" as all I have done for a long time is type completion shortcut "rcom" for "routine comment" or "vcom" for variable comment "ccom" for class comment, "hcom" for header comment, "scom" for source comment and they dump a tabbed template right into the editor courtesy of the Code Snippit Library completion shortcut. Tacos!


But most importantly, if in the attempt to make this new Xcode commenting via command key feature, they broke the commenting system or are changing it in a fundamental way so such comment blocks no longer work "as designed" in Xcode, this puts 100's of 1000's of lines of code I have in a world of hurt.


If you made it this far and are not familar with what you read, here is how to implement uber-cool documentation (oxymoron?) in Xcode 7 and prior:


Show the snippit pane in your editor

Since there is no "+" button to create a new snippit drag any of your code into the snippet area to create a new snippit

(at least there is drag and drop which is great but come on Xcode dev, get with the Mac design already, "intuitive" means from what I have seen and done b4)

Up pops a snippit editor

Change the "Title" field from "My Code Snippit" to "Routine Comment"

In the "Summary" field put "Comment block before first line of function or method code"

Platform should already be set to "All"

Set Language to "Generic"

Set Completion Scopes to "All"

In the snippit body entry that has no title below "Completion Scopes" paste in the following:


/!

@method <#Method Prototype#>

@abstract <#One Line Abstract#>

@discussion <#Lengthy Discussion#>

Status: <#development/finished#> - <#name#> - <#date#>

@see <#Reference Material Links etc#>

@param <#Param Variable#> <#Parameter Description#>

@return <#Return Value Description#>

*/


And that's it, click the "Done" button. Note that the <#some text#> creates the tab-able delimiters to replace when the rcomm text is expanded in your source.

Accepted Reply

+1 for this as well. The @see tag is completely failing to render in Quick Help. Is this worthy of an Apple Radar bug?

Replies

sorry the leading "/*" got changed by the forum to "/!"

+1 for this as well. The @see tag is completely failing to render in Quick Help. Is this worthy of an Apple Radar bug?

Is this worthy of an Apple Radar bug?

Yes. Even if this was a deliberate change, it’s still worth filing a bug indicating that it’s causing you problems. Please post your bug number, just for the record.

ps This thread is discussing HeaderDoc-style comments. You might want to take a look at Doxygen-style comments, like this:

/*! <#description#>
*  \details <#description#>
*  \param <#name#> <#description#>
*  \returns <#description#>
*/

See this post for more info.

Share and Enjoy

Quinn “The Eskimo!”
Apple Developer Relations, Developer Technical Support, Core OS/Hardware

let myEmail = "eskimo" + "1" + "@apple.com"