CODEWITHSUNDEEP
objective-cxcodedoxygencommentscode-documentation
m Jae
m Jae

Reputation: 725

Create "Quick Help" Entry in Xcode

How do I create quick help entries in Xcode for my own code? I just want it as a coding support, meaning like the Eclipse functionality when coding Java. In eclipse you get a comment you entered above a method when hovering a method somewhere else.

The Xcode equivalent seems to be the "Quick Help".

Is there really no other way than using Doxygen? Doxygen seems like overkill for the small project I'm working on. At the moment I do know for sure that I only want the quick help populated thoroughly, so please avoid any hints like, "you have to create a documentation for your project".

I would really appreciate any help as the only thing I could find on this topic was this question.

But as you can see, no solution is available.

Upvotes: 35

Views: 10496

Answers (7)

Samuel-IH
Samuel-IH

Reputation: 813

A slightly modified, and code snippet version of Lewis' Swift 3 answer:

    /**
 <#summary#>

 <#discussion#>
 Example:
 ````
 <#example codeblock#>
 ````
 - important: <#important stuff here#>

 - version: <#version number#>

 - Parameter <#param1#> : <#description#>
 - Parameter <#param2#> : <#description#>

 - Throws: <#error description#>

 - Returns: <#return value#>

 */

I had to use individual Parameter syntax because Xcode will otherwise ruin the formatting of nested parameters in the snippet (for whatever reason).

Upvotes: 1

Lewis Black
Lewis Black

Reputation: 51

For anyone interested in how to do this in Swift 3.

/**
 Makes a route

 - Parameters:
      - Parameter1 : The *x* component.
      - Parameter2 : The *y* component.
 - Throws: Error.IncorrectX if the x parameter 
    is less than zero.

 - Returns: A new integer answer which is x*y.

*/

The parameters 1 and 2 have to be the correct names you have given your parameters.

Upvotes: 2

memmons
memmons

Reputation: 40502

Xcode 5 now has built-in support for DOxygen style comments. So, you can comment your methods like this:

/*!
 * Provides an NSManagedObjectContext singleton appropriate for use on the main 
 * thread. If the context doesn't already exist it is created and bound to the 
 * persistent store coordinator for the application, otherwise the existing 
 * singleton contextis returned.
 * \param someParameter You can even add parameters
 * \returns The a shared NSManagedObjectContext for the application.
 */
+ (NSManagedObjectContext *)sharedContext;


Inline help will look like this:

inline help



Quick help will look like this:

quick help



And sidebar help will look like this:

sidebar help

Here's a handy code snippet you can add the your Xcode Code Snippet library to make method documentation simple:

/**
 <#description#>
 @param <#parameter#>
 @returns <#retval#>
 @exception <#throws#>
 */

doxygen code snippet

Now, you can just type "doxy" and poof! You have your doxygen template.

Upvotes: 5

cbowns
cbowns

Reputation: 6365

As of Xcode 5.0, Doxygen and HeaderDoc formatting for variables and methods is automatically parsed and rendered in the Quick Help popover. More information about it here, but here's some key bits:

/**
 * Add a data point to the data source.
 * (Removes the oldest data point if the data source contains kMaxDataPoints objects.)
 *
 * @param aDataPoint An instance of ABCDataPoint.
 * @return The oldest data point, if any.
 */
 - (ABCDataPoint *)addDataToDataSource:(ABCDataPoint *)aDataPoint;

renders in Xcode as:

As for properties, it's as easy as:

/// Base64-encoded data.
@property (nonatomic, strong) NSData *data;

When option-clicked, this lovely popover appears:

Upvotes: 6

Alex Gray
Alex Gray

Reputation: 16463

Yes... you can.. Here is a ready-made "Snippet" you can drag or auto-complete, etc...

/** 
 * <#summary#>
 * @param <#name#> <#how you gonna get it?#>
 * @param <#name#> <#really, there's more?#>
 * @return <#name#> <#what do you want!#>
 */

Drag that "onto" the snippet "thing" and like, you know.. set it up.. enter image description here

and there ya have it...

enter image description here

Upvotes: 29

Binarian
Binarian

Reputation: 12446

You can create a DocSet with AppleDoc easily and it generates QuickHelp-Links (option ⌥ + mouse click).

Examples and the Binary for the Terminal Command are here:

http://gentlebytes.com/appledoc-docs-examples-basic/

I tried it and only used the basic switches and the new DocSet works with QuickHelp: 

./appledoc --project-name testdocs --project-company "My Company" --company-id com.mycompany --output ~/Desktop ~/Desktop/appledoc-master

Upvotes: 1

lkraider
lkraider

Reputation: 4180

I think the only way is to create a Documentation Set for your code and then install it on XCode:

Xcode 4′s contextual help, which Apple calls “Quick Help,” relies entirely on the installed documentation sets. Xcode 4 automatically downloads the documentation sets (including updates) for the Mac OS and iOS APIs but you can install third-party sets as well.

(...)

Once you create your documentation set, you can install it in Xcode’s preferences (under the Documentation tab). Assuming the doc set is correctly built and installed, Quick Help should “just work.” Of course this is of limited use unless you’re sharing complex API with a group or the wide world.

source: http://xcodebook.com/2011/04/providing-your-own-quick-help/

Apple's Documentation Set guide: http://developer.apple.com/library/mac/documentation/DeveloperTools/Conceptual/Documentation_Sets/

Upvotes: 9

Related Questions