What are the new documentation commands available in Xcode 5? [closed] - objective-c

Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
One of Xcode 5's new features is the ability to document your own code with a special comment syntax. The format is similar to doxygen, but appears to only support a subset of those features.
Which commands are supported, and which ones aren't?
Do any of their usages differ from doxygen?

Here is an example of all the options I have found as of Xcode 5.0.2
That was generated with this code:
/** First line text.
Putting \\n doesn't create a new line.\n One way to create a newline is by making sure nothing is on that line. Not even a single space character!
#a Italic text #em with ##a or ##em.
#b Bold text with ##b.
#p Typewritter font #c with ##p or ##c.
Backslashes and must be escaped: C:\\foo.
And so do ## signs: user##example.com
Some more text.
#brief brief text
#attention attention text
#author author text
#bug bug text
#copyright copyright text
#date date text
#invariant invariant text
#note note text
#post post text
#pre pre text
#remarks remarks text
#sa sa text
#see see text
#since since text
#todo todo text
#version version text
#warning warning text
#result result text
#return return text
#returns returns text
#code
// code text
while (someCondition) {
NSLog(#"Hello");
doSomething();
}#endcode
Last line text.
#param param param text
#tparam tparam tparam text
*/
- (void)myMethod {}
Notes:
The commands must be in a /** block */, /*! block */, or prefixed with /// or //!.
The commands work with the # (headerdoc style) or the \ (doxygen style) prefix. (I.e. #b and \b both do the same thing.)
The commands usually come before the item they are describing. (I.e. if you are trying to document a property, the comment must come before the #property text.) They can come afterwards, on the same line, with /*!<, /**<, //!<, ///<.
You can add documentation to classes, functions, properties, and variables.
All of these commands appear in dark green text to signify that they are valid commands, except for #returns.
You may need to build your project (or restart Xcode) before the latest changes to your documentation appear.
Where to see the documentation:
1. During code complete, you will see the brief text:
This will show the brief text (with no formatting); if no brief text exists, it will show a concatenation of all the text up to the first #block; if none exists (e.g. you begin with #return), then it will concat all the text striping away all #commands.
2. Option-clicking an identifier name:
3. In the Quick Help Inspector panel
(See first screenshot.)
4. In Doxygen
Since the commands in Xcode 5 are compatible with Doxygen, you could download and use Doxygen to generate documentation files.
Other Notes
For a general introduction to Doxygen and how to document Objective-C code, this page seems like a good resource.
Descriptions of some of the supported commands:
#brief: will insert text at the beginning of the description field, and is the only text that will appear during code completion.
The following don't work:
\n: doesn't generate a newline. One way to create a newline is by making sure nothing is on that line. Not even a single space character!
\example
The following are not supported (they don't even appear in dark green):
\cite
\docbookonly
\enddocbookonly
\endinternal
\endrtfonly
\endsecreflist
\idlexcept
\mscfile
\refitem
\relatedalso
\rtfonly
\secreflist
\short
\snippet
\tableofcontents
\vhdlflow
\~
\"
.
::
\|
Apple reserved keywords:
Apple uses what appears to be reserved keywords that only works in their documentation. Although they appear in dark green, it looks like we cannot use them as Apple does. You can see examples of Apple's usage in files such as AVCaptureOutput.h.
Here is a list of some of those keywords:
#abstract, #availibility, #class, #discussion, #deprecated, #method, #property, #protocol, #related, #ref.
At best, the keyword will cause a new line in the Description field (e.g. #discussion). At worst, the keyword and any text following it will not appear in the quick help (e.g. #class).

Swift 2.0 uses the following syntax:
/**
Squares a number.
- parameter parameterName: number The number to square.
- returns: The number squared.
*/
Notice how #param is now - parameter.
You can also now include bullets in your documentation:
/**
- square(5) = 25
- square(10) = 100
*/

Senseful:
You may need to build your project before the latest changes to your documentation appear.
Sometimes this hasn't been enough for me. Closing Xcode and opening the project back up usually remedies those cases.
I'm also getting different results in .h files and .m files. I can't get new lines when the documentation comments are in a header file.

Most of the formatting has changed for Swift 2.0 (as of Xcode7 ß3, also true in ß4)
instead of :param: thing description of thing
(as it was in Swift 1.2)
it is now - parameter thing: description of thing
Most of the keywords have been replaced by - [keyword]: [description] instead of :[keyword]: [description]. Currently the list of keywords that don't work includes, abstract, discussion, brief, pre, post, sa, see, availability, class, deprecated, method, property, protocol, related, ref.

Related

Where can I find a complete list of keywords (of the form ${ ... } ) that can be used in netbeans "code template"

The complete list of keywords that are legal in creating code templates in Netbeans would be accompanied by some documentation, making the "list" a reference. A line from the reference might look like:
${cursor} says to put the cursor at this point in the generated line
Working examples might be included in the reference, such as:
User-defined word to invoke the template: edfold
The template as it would appear in the Netbeans 8.2 RC > Tools > Options > Editor > Code templates tab:
${no-indent}//
// <editor-fold desc="***** ${cursor} *****" >
//
How it works: When I type edfold and hit the Tab key, the template is pasted into my document at the cursor position and looks like the following:
//
// <editor-fold desc="***** # *****" >
//
The cursor is positioned between the 5th and 6th asterisks that follow desc, so that I can then type whatever brief documentation that I wish, if any.
So where is the list of such keywords and their syntax and meaning? Such as:
${cursor}
${selection}
${no-indent}
${arg}
${Type}
and who knows how many more
It just hit me that there are OTHER keywords, two of which I unwittingly used above (I noticed them in someone else's code template and figured out how to use them):
desc
editor-fold
Surely there are other such identifiers to include in the reference.
By the way, the code template above is cute (or not) but is useless without a companion code template:
keypress:
endfold
Code template in editor:
// </editor-fold> ---------------- ${cursor} -------------------
Wherever the first inserted code template is located in your code, the second template must be below it. There is a "collapse" symbol "-" at the left of the first template. Clicking it collapses the code between the two templates. The symbol then changes to "+" and will expand the collapsed code when clicked.
EDIT
I just found this equivalent code template to the edfold and endfold pair just completed. Easier to code, up to a point, and harder to learn to use, but worth it, in the long run. Just highlight text to "hide" by folding, look for the line with the "Light Bulb", click Alt+Enter, and click "Code Folding". (Ctrl+Z to undo!)
But please see my (much better) Answer than this (was a) Question below.
Egg on my face... Googled topic, scanned all hits WAY too fast. In particular, "netbeans 8.2 code templates" pointed to this page involving PHP (think Java), which contained a lot of invaluable info about PHP that applies directly to Code Templates in Netbeans 8.2.
So, that link is part of a manual of sorts for learning how to create Code Templates for Netbeans 8.2 (in particular, and PHP in general).
The reference that I asked for--complete list of keywords (of the form ${ … } )--implies a list of all keywords or reserved words, like ${cursor} and ${selection} that permeate the list of provided Code Templates. But in a sense, that is the list. It is exactly those two Reserved Names. There are no others. Short list.
In the list of provided Netbeans Code Templates, there are a LOT of words that share the same $(...) syntax, but most are placeholder names or parameters that you decide the name and (probably-simple) meaning of.
If a code template contains, for example, class ${className}, the word class is Java code and ${className} is a parameter or placeholder. When the IDE expands the template, class is entered and ${className} turns into class_name, which the IDE automatically selects for editing, suggesting for you to enter the name of the new Java class being defined.
This non-trivial, but understandable, code template and much of what follows it explains much of the process for creating Code Templates. The heading Inserting the code template with code completion ends the explanation, but here is a sort of note of summary from further down:
The syntax of a "code template parameter" is a dollar sign, $, followed by the
parameter's definition between curly brackets {...}. Within this syntax, template
parameters have one of four forms:
* A reserved name that gives processing instructions to IDE (cursor or selection, only)
* An arbitrary placeholder name, such as ${SomeName}
* A descriptive parameter name [that hints at its meaning]
* Pre-defined parameters (??)

Xcode not formatting document comment properly for Objective-C code

I added the following comment with backtick for code:
/** Checks if the given data is of type `list`. */
+ (BOOL)isList:(id)object {
// ..
}
but the backtick prints as in the Xcode quick help:
How to get Xcode to display code formatted properly? It works fine when documenting Swift source.
As discussed in the comments above, in Objective-C documentation comments you can use #p or #c to display Typewriter font in the QuickHelp documentation. Whereas Swift documentation comments accept Markdown (using the backticks)
While this answers is relatively old, it still lists a good amount of the options available in Objective-C documentation comments: https://stackoverflow.com/a/19169271/7833793
Here's a brief example:
/// Here's how to use #c Typewriter #c Font
- (void)myMethod {}
Which displays this in the QuickHelp:

Jetbrains IDE: How to generate custom "todo" tags?

I have figured out how to download and install new color schemes.
It is after I did this that I noticed that IntelliJ will still color the following line yellow:
// ToDo: implement
Further, this coloration is independent of the color schemes I download. So, I now surmise that it is colored that way due to some logic specific to the Intellij.
I also use Pycharm and CLion, and suspect it would be the same situation across all three.
Here is the question: how do I access these settings/xml/logic and specify that I want say, 5 types of comment tags with colors A, B, C, D, E, such that I can call them by saying stuff like:
// T-A: File read in (t would be type)
// T-B: transform data
// T-C: linear section
// T-B: transform again
// T-D: parallel section
// T-E: MPI update
// T-B: array read in
// T-A: File read out
// etc.
So that I can basically color code the regions of a project, rather than just use the "ToDo" line?
You can go to Preferences | Editor | TODO. And there you can add / remove / edit your own patterns and filters, including color scheme:
After that, in your TODO window there's a Filter button with option to Edit filters, so you can easily find all places in your code with your custom patterns.
The problem was already answered quite well but I would like to add the usage of non-word tags like ???.
This requires to adopt the regex boundary character from \b (word boundary) to \B (non-word boundary). This leads to the final pattern \B\?\?\?\B.* to match:
code // ??? comment
code // ???: comment
This was not directly asked but may helps other with the same problem as I met...
See also https://www.jetbrains.com/help/idea/regular-expression-syntax-reference.html

Incorrect doxygen formatting on only one line

The heading at the start of the comment block shown in the C code below is formatted incorrectly in both HTML and PDF output as \verbatim text.
All other Doxygen comments I have in this file work perfectly (they are all VERY similar as the file provides functions that conform to a type).
I have tried removing all preceding Doxygen comments from the file (except the #name) to rule out incorrect block formatting closing, removing the heading spec (#'s) changing the heading text (eg "foo") in case of incorrect characters, removing the later \verbatim block, removing this entire comment block itself to see if the problem transferred to the next one, but nothing seems to change!!
How can I get the heading to format correctly?? Thanks.
code:
/** # *IDN? - Identification query #
* This query allows the instrument to identify itself. It responds with a `<`string`>` consisting of four fields
* separated by commas. The four fields are determined by constants defined in the application
* specific settings in config.h and appear in the following order:
* \verbatim MANUF,MODEL,SERIAL,FIRMW \endverbatim
* See the config.h file description for information on each of these fields.
*
* #param parameters None
* #param query `*IDN?`
*/
extern int16_t IDN (double * parameters, bool query);
How this looks in PDF:
How this looks in HTML:
EDIT: The comments for the OPC function:
/** # *OPC - Operation Complete Command. #
* This command causes the device to set the operation complete bit in the standard event status register when
* all pending device operations have completed.
*
* The query responds with an ASCII "1" when all pending device operations are complete.
*
* #param parameters None
* #param query `*OPC?`
*/
extern int16_t OPC (double * parameters, bool query);
Finally solved this, though Im still unsure as to the cause.
Basically I rewrote the documentation comment a bit at a time (I was trying to see if I could isolate any one item that caused it).
I started with a one word comment, when that appeared correctly I slowly added more bits, rebuilding after each addition. I now have the full comment, exactly as before, but now working as intended
Puzzling... maybe doxygen only rebuilt that part after it detected the comment being deleted and started again and that cleared whatever the issue was?? Meh, it's fixed anyway. Thanks for the suggestions.

automatically insert header doc comments in Objective C?

Since XCode 5 now supports reading header comments directly from header files, it has become increasingly interesting, to document functionality in a consistent way.
I therefore try to find a tool that can automatically insert header doc comments in Objective C header files, but can't seem to find one?
Basically I would like a took that could write something like:
/*!
<desc method.>
#param parmA
<desc of parmA>
#param parmB
<desc of parmB>
#result
<desc of result>
*/
- (CO2 *)doSomething:(typeName)parmA withSomething:(typeName)parmB;
I found this very handy Xcode plugin to write all the default comment code for you.
https://github.com/onevcat/VVDocumenter-Xcode
EDIT
As of Xcode 8, there is a new shortcut available that has the same behaviour as the VVDocumenter plugin.
Place the cursor above any function, class, struct,... and hit ⌘ + ⌥ + /
This will generate a comment accordingly to where you placed the cursor.