This question already has answers here:
What are the new documentation commands available in Xcode 5? [closed]
(4 answers)
Closed 8 years ago.
This question is for reference purposes.
In the "Fonts & Colors" tab of the Settings window of Xcode, there's a setting for documentation comments (and keywords)? What are they?
Feel free to enhance this answer.
Documentation comments are just (Objective-C) comments marked as documentation. They are treated the same way as normal comments, except that you can set another color and font in Xcode. Some documentation software may even use these comments to create automatically documentation from given header files and other source code.
Documentation comment keywords are keywords that give semantical meaning to text that follows after the keyword in a documentation comment.
You can create inline documentation comments with three slashes (instead of two in normal comments), and block doc. comments with two stars instead of one (instead of one in normal comments). Example:
// Normal inline comment
/// Documentation comment
/* Normal block
comment */
/** Documentation block
comment */
You can create documentation comment keywords by specifying a keyword (one word only) after the "at" symbol. Example:
- (void)sendMessage: (id)sender;
/// #description Sends the receiver.
/// #available Version 1.0 through 2.2
Appledoc is a tool for creating a documentation set from your source code (including documentation comments and method signatures) and getting it to install and reload inside Xcode when needed. It's a command-line program and has instructions for how to incorporate it into your Xcode build process.
Once you have a documentation set you can add it to Xcode via Preferences > Downloads > Documentation.
The special keywords starting with an #-sign is also called HeaderDoc tags. A list of them can be found in the HeaderDoc User Guide. Please note that some of them are Objective-C and some are C++.
For those who did not watch the latest keynote: With Xcode 5 this feature will be built in. It is already available in the current developer preview (called quick help, like announced here).
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:
Quick help will look like this:
And sidebar help will look like this:
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#>
*/
Now, you can just type "doxy" and poof! You have your doxygen template.
There are a number of tools such as Doxygen, Javadoc, and others which recognize "special" comments (known as documentation comments) to automatically generate documentation for the code.
Typically, documentation comments start with a special sequence such as /** (as opposed to just /*) and contain special keywords that often have a special start symbol such as #. There are a lot of similarities between the different comment documentation generators, most of which accept "#param" to document parameters, "#return" to document return values, "#throws" to document exceptions, etc.
In the context of Xcode's syntax highlighting, documentation comments are those with one of these special start sequences that Xcode happens to recognize. It should be noted that there a specific set of such comments that Xcode properly recognizes; for example, the Doxygen tool also allows /*! and //! (with an exclamation) to indicate the start of documentation comments, but Xcode doesn't recognize it.
Related
There are several doxygen commands whose purpose is to create links in the documentation (#link, #ref).
I am currently using the #ref command to create a link to a custom file, written in a language not supported by doxygen (xml).
I would like to alter this link so that it points to a precise line in the file.
Is there a doxygen command that allows to do that ?
I'm not sure that \ref or \link can do this. However, if they could, one problem of adopting this approach is that the links will become invalid if you change the contents of the file you are linking to without changing the link. This is one of the problems of separating source code and documentation.
Rather than linking to a particular line in another file why don't you include the particular part of the file you are interested in in the documentation? You could either:
include the whole file with \include (there is also \includelineno) and just reference relevant parts of it in the text (e.g. "function xxx in the code below"), or
include snippets of the file where you need to refer to them in the documentation using \snippet.
Edit: Alternatively, you could use the \dontinclude command which, together with the \line, \skip, \skipline, and \until commands allows you to include specific lines/blocks of a particular file. See the example in the \dontinclude documentation.
I would like to provide custom definitions for financial terms (in different languages) in my application using the UIReferenceLibraryViewController, which was introduced in iOS 5.
However, I have not found any information on how to add custom definitions to the reference.
Do you have any suggestions on how to implement this useful feature?
From the documentation:
It should not be used to display wordlists, create a standalone dictionary app, or republish the content in any form.
So, you won't be able to add new definitions.
A quick search on github gives some dictionary sample apps that could be a starting point. See : http://github.com/mattneary/Etymology-for-iPhone or http://github.com/ioseb/LinGEO
Im using doxygen outside of its design, but well within its capability. I have a bunch of essentially text files, appended with some doxygen tags. I am successfully generating doxygen output. However, somehow doxygen occasionally discovers what it assumes to be a variable, and proceeds to document it using surrounding text, causing a lot of confusing documentation. I cant see any direct relationship between these anomalies, only that they're reproducing the same output on each run, and what I can see is at least some are next to a ';' or a '='.
I only want doxygen to document what I've manually tagged. I am hoping to remove any occurrence of these anomalies, however I cannot alter existing text. I can only add doxygen tags, or alter the configuration file. Any ideas?
Many thanks.
Because in my particular case, I do not need any automatically generated documentation, only that which I have tagged with doxygen tags, setting
EXCLUDE_SYMBOLS = *
removes any instance of doxygen "finding" and documenting variables. This however may remove any ability to find any class declarations, namespaces or functions, however this is acceptable for me.
We've got a large codebase of Java (with a smattering of Groovy mixed in) that, by and large, has no javadocs written for it.
However, much of the code is reasonably well documented in "old-school" comments scattered throughout the body.
We're now on something of a push to try and get things documented a little better - Javadocs are now being generated on a regular basis, for example. As a stopgap measure, it would be really nice if javadoc would "scrape" the body of the class (or function, or whatever) and toss all the comments within into a "stub" javadoc.
Is there a way to do that?
Sounds like a bad idea, given that javadocs typically describe purpose and usage of elements, and code body comments are (or should be) about the details of implementation.
But if you must, you clearly need to write your own custom doclet that works in concert with a java source file parser (either 3rd party or your own). For each processed class, you would first run the parser on the source file for that given java class and harvest the internal comments, and then augment the (standard) html produced by the (standard) doclet to add the code comments.
A possible strategy that would help make the resultant javadocs sensible would be to include a given method's internal comments for the javadoc for that method. Just use a 'pre' closure and append the parsed comments of the method at the end of the generic javadoc html.
Is there any kind of standard across editor and IDEs for expanding snippets?
Specifically, I would like to write a patch for an API that would provide a code snippet database that could be imported into different editors/IDEs and expand on demand.
I am writing something for vim (my editor of choice so that)
:expand theme_some_function
would then insert
/**
* Override of theme_some_function($&arg)
**/
MYMODULE_some_function(&$arg1) {
// contents of the function go here
}
which is how you override a function in Drupal.
Originally I was writing this so that it would go find the file through ctags and copy the function and s/foo/bar/ what needs to be changed. It was suggested that I could expand this to other editors, so I was wondering if there was a standard that I might use.
But in general, is there any kind of editor standard that might give me ideas about opportunities to write something for many editors at once?
There isn't really any such editor standard, no.
I've not found any such standard. But here are a few points for exploration.
• Microsoft publishes a spec for an XML-based format of code snippets.
Code Snippets Schema Reference (Visual Studio 2012)
• Wikipedia has an article on code snippets but makes no mention of standards.
• This web page for Code Collector Pro (Mac OS X app) mentions:
Support for .snippet Files – A new common file format for all snippet managers
…but provides no information or links about such a format.