This question already has answers here:
How to create documentation for a c++ project?
(1 answer)
Objective-C Documentation Generators: HeaderDoc vs. Doxygen vs. AppleDoc
(3 answers)
Closed 8 years ago.
Is there some alternative way to document your own functions/methods/variables in objective-c?
Like XML documentation in C# and java doc in Java.
I would recommend you to use Doxygen. It is what we use internally at work and it works really well. The fact that you could then also use the same system for other languages is also an added bonus if you eventually come to need that.
There is a good guide for automating the generation of your Doxygen docs with your builds here: http://www.guidebee.biz/forum/viewthread.php?tid=168
There has been some development since the other answers have been posted.
AppleDoc has evolved and become quite nice. It creates doc pages in the style of Apple's own pages, which is what you are after if I interpret your question correctly.
Documentation of the comments format here.
I'm having a deja vu ;-) Anyway, it looks like Doxygen can handle Objective-C as well; I have not personally tried it though.
Good news everyone! 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.
Related
I'd like to be able to Alt-Click an instance variable (or a method) as part of the program i created and read what it's purpose is.
The fact that Xcode is telling me the class variable is declared at - is nice but not enough. In this case i'd like to see custom text i typed to describe what an asset really is. Additionally type of the ivar would also be useful to know.
How can this be done? In this case, i wonder what exactly did i mean by assets
I specifically wonder if this information can be viewed from inside Xcode, similar to how Eclipse shows JavaDoc content.
You would need to create a documentation set for your project and install it in Xcode. appledoc can help you with this. This is a command-line tool that can generate documentation in Apple's style from specially formatted comments in your headers. You can also integrate this into your build process with a run script build phase, so that documentation is always up-to-date.
For small projects, it's usually not worth the effort though and you're probably better off just adding comments to your header files and jumping there with Cmd-click (Ctrl+Cmd+left-arrow to go back to where you came from).
You'll probably want to take a look at Apple's documentation on Documentation Sets as well as their article on generating doc sets using Doxygen. The latter is based on Xcode 3.x, so how relevant it is is somewhat questionable, but it'd be a good idea to take a look nonetheless.
That said, if you decide to use Doxygen (alternatives like HeaderDoc can be used for documentation, but I'm not sure what's available to you as far as creating doc sets goes), it looks like the main point is you'll want to throw GENERATE_DOCSET=YES into your Doxyfile (or whatever you decide to call it). After that, you'd just throw the results into ~/Library/Developer/Shared/Documentation/DocSets (according to Doxygen's documentation). I don't know whether this works in Xcode 4.x - it's worth a shot though, and it'd be nice to hear back on it.
Note: most of this was based on this answer by Barry Wark. Figure credit is due there, since I wouldn't have bothered looking into this were it not for his answer.
I'm new to Mac programming. When I open sample projects, I often get 'deprecated' code warnings during a build. I'd like to fix these and get a clean build using XCode 4.
When Apple deprecates something, how do I find out why it was deprecated?
More importantly, how do I find out what is the 'new' correct way to implement the deprecated task?
For example, I'm seeing deprecation warnings for: QTMovieSizeDidChangeNotification, writeWithBackupToFile, documentForFileName, shouldCreateUI, setShowPanels, QTMovieCurrentSizeAttribute, and many others.
Look up the method in the documentation - they show the deprecated methods and tell you what the preferred methods are.
For example writeWithBackupToFile is clearly marked as deprecated and shows that writeSafelyToURL:ofType:forSaveOperation:error: should be used instead.
Same with shouldCreateUI which shows that either openUntitledDocumentAndDisplay:error: or openDocumentWithContentsOfURL:display:error: should be used instead.
Also, read the other methods in the documentation - you'll find things that do what you need. For example you list QTMovieSizeDidChangeNotification as being deprecated (in QuickTime 7.6.3). Right above it in the documentation you can see QTMovieNaturalSizeDidChangeNotification which has been available since QuickTime 7.6.3). Use that instead.
Look for the deprecated things in the documentation. Usually, there's a note that suggests what to use instead.
For example, the documentation for writeWithBackupToFile:ofType:saveOperation: says:
This method is called by action methods to save document contents to a file. (Deprecated in Mac OS X v10.4. Use writeSafelyToURL:ofType:forSaveOperation:error: instead.)
Search the documentation for that method/function/constant. It should list there what to use instead, or at least bring up a class that obviously has other methods that do something similar.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I'm currently using JSDoc Toolkit to document my code, but it doesn't quite fit - namely, it seem to struggle with describing namespaces properly. Say you have two simple classes in each their files:
lib/database/foo.js:
/** #class */
function Foo(...) {...}
/** #function ... */
Foo.prototype.init(..., cb) { return cb(null, ...); };
module.exports = foo;
And then something inherited lib/database/bar.js:
var Foo = require('./foo');
/**
* #class
* #augments Foo
*/
function Bar(....) {...}
util.inherits(Bar, Foo);
Bar.prototype.moreInit(..., cb) { return cb(null, ...); };
In the generated documentation, this is output simply as Foo and Bar, without the leading database (or lib.database), which are quite necessary when you don't have everything in a global scope.
I've tried throwing #namespace database and #name database.Foo at it, but it doesn't turn out nice.
Any ideas for making JSDoc output something more suitable, or some entirely different tool that works better with Node.js? (I looked briefly at Natural Docs, JSDuck and breezed over quite a few others that looked quite obsolete...)
JSDoc is a port of JavaDoc. So basically the documentation assumes classical OOP and that's not suited to JavaScript.
Personally I would recommend using docco to annotate your source code. Examples of it can be found for underscore, backbone, docco.
A good alternative to docco is groc
As for an actual API documentation, I personally find auto generated documentation from comments just does not work for JavaScript and recommend you hand-write your API documentation.
Examples would be underscore API, Express API, nodejs API, socket.io docs
Similar StackOverFlow questions
Generating Javascript documentation
YUIDoc is a Node.js application that generates API documentation from comments in source, using a syntax similar to tools like Javadoc and Doxygen. YUIDoc provides:
Live previews. YUIDoc includes a standalone doc server, making it trivial to preview your docs as you write.
Modern markup. YUIDoc's generated documentation is an attractive, functional web application with real URLs and graceful fallbacks for spiders and other agents that can't run JavaScript.
Wide language support. YUIDoc was originally designed for the YUI project, but it is not tied to any particular library or programming language. You can use it with any language that supports /* */ comment blocks.
NOTE: Dox no longer outputs HTML, but a blob of JSON describing the parsed code. This means the code below doesn't work terribly well any more...
We ended up using Dox for now. It is a lot like docco, that Raynos mentions, but thows all of it in one bit HTML-file for output.
We hacked this into our makefiles:
JS_FILES := $(shell find lib/ -type f -name \*.js | grep -v 3rdparty)
#Add node_modules/*/bin/ to path:
#Ugly 'subst' hack: Check the Make Manual section 8.1 - Function Call Syntax
NPM_BINS:=$(subst bin node,bin:node,$(shell find node_modules/ -name bin -type d))
ifneq ($(NPM_BINS),)
PATH:=${NPM_BINS}:${PATH}
endif
.PHONY: doc lint test
doc: doc/index.html
doc/index.html: $(JS_FILES)
#mkdir -p doc
dox --title "Project Name" $^ > $#
It is not the prettiest or most efficient documentation ever made (and dox has quite a few minor bugs) - but I find it work rather well, at least for minor projects.
Sorry, I was not on StackExchange a year ago, but I believe the answer to your original question is to use the #memberOf tag:
/** #namespace */
database = {};
/**
* #class
* #memberOf database
*/
function Foo() { ... };
http://code.google.com/p/jsdoc-toolkit/wiki/TagMemberOf
This tag may or may not have existed when you asked your question.
Found a really nice solution for the problem: doxx.
It uses dox as mentioned above and converts this to nice HTML afterwards. Has a nice usage and worked great for me.
https://github.com/FGRibreau/doxx
I work with JSDoc and is very efficient, in addition to easy, but when projects have many alternate libraries are quite complicated development. I found Groc a very good tool based on Docco and works with other languages like: Python, Ruby, C + +, among others...
Furthermore Groc working with Markdown in GitHub which can be much more efficient when working with git as version control. Further helps assemble pages for publishing on GitHub.
You can also use the task manager GruntJS through grunt-groc example:
Install package:
npm install grunt-groc --save-dev
configure in your task file:
grunt.loadNpmTasks('grunt-groc');
And the config task:
// Project configuration.
grunt.initConfig({
groc: {
coffeescript: [
"coffee/*.coffee", "README.md"
],
options: {
"out": "doc/"
}
}
});
For run task:
grunt.registerTask('doc', ['groc'])
I'm practicing OOP for 2 years (for real) and I know how to consume objects and packages and I'm developing stuffs mostly using C# .
but I have a problem with consuming unknown objects and packages as an instance :
for now I am working on an enterprise like website and for part of our job we need to consume RSS. I decided to use "System.Xml.Xpath"
and my real problem is:
for using system.xml.xpath I should look at manual and read it carefully and I don't want to do that every time.A plain example of that is like following code :
XPathDocument xp = new XPathDocument(sites[2]);
XPathNavigator nav = xp.CreateNavigator();
XPathNodeIterator it = nav.Select(xpath3);
foreach (XPathNavigator n in it)
{
//get elements here
}
//another way of iterating elements is
while(it.movenext())
{
//it.current.Value;
}
for the "foreeach" part I got it from MSDN manual and I guess I could get this simple fact by looking at class structure.
but I don't know which structure I should look.
I know how to read tooltips and I'm familiar with things like : [] / collection / enum /generic / Ienumerable / Idisposable etc...
but I think there is something about reading class behaviors and I'm missing that part.
for make it more lucid :
I know whenever we have a class that inherited from IEnumerable so we can use foreach statement against that class to iterate it through
my real problem is I think classes are self described enough to not to look at manuals all the time but I don't know how/where to read those descriptions of classes so I need your advice to get more familiar with how to reading classes without looking at manuals.
best regards.
Classes can (and should) be documented with source code comments, and in many languages you can generate API documentation from these comments (in HTML, XML or other format). In Java it is called Javadoc; I don't know the C# term. If this is what you call "manual", then this is your primary source of information. Other than reading the source code comments and the code itself (which you often don't have access to, especially in the MS universe). If you don't find enough information in the API documentation, you can always try googling for more explanation, tutorials or usage examples.
Hope this helps; I am not entirely sure I understood your question though. If this is not the answer you are looking for, please clarify.
There is a GetILAsByteArray method in MethodBody class which gives body of a method. I am looking for converting this byte array into more understandable IL instructions (into a List or something like that). What resources, open source code or api available are there to help me understand and convert this byte array (or do it for me)?
I found this but it does not work with generics. I am pretty much looking for guidance to convert understand these bytes in all framework versions.
CLI Documentation is also helpful for learning IL instructions but I cannot see how to use it to make these bytes make sense.
I just wrote an extension method to get a more understandable list of instructions using GetILAsByteArray. It's quite simple, the API is like:
public static IList<Instruction> GetInstructions (this MethodBase self);
You can read more about the implementation in my blog post. Or you can go take the implementation and start using it.
Have a look at the Mono.Cecil library.
It is a huge undertaking. I wrote the starts of an IL reader and it had a pretty good amount of opcodes implemented: but you will need to finish it.
http://svn.ensemble-os.org/tags/OldOCJ/CIL/
There is also MONO Cecil, which is feature-complete.