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:
Related
I'm using Swift 3 and xcode 8. I'm very new to objective-C and fairly new to swift, so maybe this is an idiot question. But here goes!
I'm bridging from objective-C to swift 3. Here's a code snippet of the objective-C:
typedef NS_ENUM(NSInteger, MaplyMapType) {
MaplyMapType3D,
MaplyMapTypeFlat,
};
#interface MaplyViewController : MaplyBaseViewController
/// #brief Initialize as a flat or 3D map.
- (nonnull instancetype)initWithMapType:(MaplyMapType)mapType;
In my Swift 3 source file I instantiate a MaplyViewController. The following is the WORKING code (it compiles and runs, and no xcode errors).
theViewC = MaplyViewController(mapType: .typeFlat)
Why does this work? From references https://developer.apple.com/library/content/documentation/Swift/Conceptual/BuildingCocoaApps/InteractingWithCAPIs.html and other references I think the correct code should be:
theViewC = MaplyViewController(mapType: .flat)
But that won't compile.
MORE INFO FROM ONE DAY LATER: Amin Negm-Awad in his comment below has almost explained this. The simple bridging rules cannot be used to produce identifiers .flat and .3D because identifier .3D is not allowed. The language reference says "Identifiers begin with an uppercase or lowercase letter A through Z, an underscore (_), a noncombining alphanumeric Unicode character in the Basic Multilingual Plane, or a character outside the Basic Multilingual Plane that isn’t in a Private Use Area. After the first character, digits and combining Unicode characters are also allowed."
So the bridging cannot result in enum identifiers .flat and .3d. I could not find any reference to explain the rules bridging uses to come up with the alternative identifies, namely .typeFlat and .type3D in this case.
Likely it is, because the other identifier (MaplyMapType3D) would be 3Dinstead of type3D, but identifiers must not start with a digit. So one has to keep type.
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.
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.
What does plus mean in method declarations in Perl6?
Here is an example from spec
submethod BUILD (+$tail, +#legs, *%extraargs) {
$.tail = $tail;
#:legs = #legs;
}
2019 Update See the section Variadic positionals destructuring; +#foo and *#foo in my answer to the SO question "variable number of arguments to function/subroutine".
In 2015 Larry Wall introduced the + parameter prefix, one of four parameter prefixes (*, **, +, |) that signify slurpy (variadic) parameters. He added it to the Rakudo compiler, added some tests, gave a brief informal description of it on the irc channel, and added a section on it to the relevant language design doc.
The example quoted in the original question is taken from an archive of an informal document written and frozen in time over a decade ago. At that time a + parameter prefix signified a named parameter as contrasted with a positional one. Nowadays we use : for that, thus:
submethod BUILD (:$tail, :#legs, *%extraargs) {
$.tail = $tail;
#.legs = #legs;
}
Your "spec" links goes to a historical document, and the syntax has long gone from Perl 6. I'm not sure what it used to do, maybe "at least one argument", in analogy to the + quantifier in regexes.
For an up-to-date specification, please read http://perlcabal.org/syn/S06.html which contains all the information on signatures and subroutines.
I'm going through the ParseKit example and trying to modify it to suit my needs and running into this problem. As soon as I pass in the grammar file to parserFromGrammar:assembler, I get an error:
[__NSArrayM objectAtIndex:]: index 0 beyond bounds for empty array
I thought maybe it was because my grammar files had token names with underscores in them. Does ParseKit support underscores? What would the method name be that gets called back? Aka would the token name "foo_bar" call a method didMatchFoo_bar?
I then took out all the underscored names and it still gives me that error. I'm using the example grammar file from the ParseKit website:
#start = sentence+;
sentence = adjectives 'beer' '.';
adjectives = cold adjective*;
adjective = cold | freezing;
cold = 'cold';
freezing = 'freezing';
Thanks
Developer of ParseKit here. 2 things:
To answer your first question, I believe the answer is YES.
I just tried out the grammar and it seems to work for me. However, I am using the latest version of ParseKit from Google Code (not GitHub. GitHub is out of date. sorry.)
So checkout ParseKit from Google Code here:
https://parsekit.googlecode.com/svn/trunk
And then select the "DebugApp" target and "DebugApp" Executable and run.
In the Xcode project, do a global search for "cold freezing beer". you'll see I've added your example as the default example run in DebugApp. Seems to work ok.