Objective-C Documentation discussion

gistfile1.txt

TLDR

If you want the simplest option just start /** [content] */ slashes in your header files. Do it before the @implementation for class comments and above methods for method documentation.
Doing this is the minimal for support in LLVM and Appledoc, which means you get CocoaDocs & XCode support.

Not TLDR

Good examples:
  https://github.com/marcransome/MRBrew/blob/master/MRBrew/MRBrew.h
  https://github.com/AFNetworking/AFNetworking/blob/master/AFNetworking/AFHTTPClient.h
  https://github.com/groue/GRMustache/blob/master/src/classes/GRMustache.h
  
Doxygen
  http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html
Appledoc
  http://web.archive.org/web/20130425104810/http://gentlebytes.com/appledoc-docs-comments/
  
  * /// and /** **/ can be used mostly interchangably, but /// has downsides as documentated below
  
  * Throughout the document add @names, these are section headers for related functions
  * Each method should have at least a single line description above it
   
  @name [Task Name] | Creates the Task List
  @param [Param Name] [Description] | Describe 
  @return [Description] | Gives info on the return value of a method
  @see [selector] | Provide a "Check this also function"
  @warning [description] | Provide some strong context for a method
  
Best Practices:
  
  Write a short “tweetable” “what it is” above a sentence above method, then a longer explanation of why, how when etc in a paragraph underneath, this will mean you have a simple method signature and a longer description underneath.
  Example: http://cocoadocs.org/docsets/AFNetworking/1.3.1/Classes/AFHTTPClient.html#//api/name/registerHTTPOperationClass:

  Class, protocol and category descriptions, need to use /** … */, otherwise only the last paragraph is used.

  @name “Task name” is the documentation equivalent of #pragma mark “Task Name”

  Only use 1 space of indent before each line, otherwise markdown formatting breaks
  
  Appledoc mangles image urls, this can be fixed by writing in HTML with a broken URL `https://`
  Example: <img src="https&colon;//raw.github.com/Fingertips/FTFontSelector/master/Project/Screenshots/iPhone%20Font%20Families.png" />