Maybe there is something out there that does this, but it seems kind of ridiculous that I cannot find a list of all the different flags that you can use in comments. For example, "@author" doesn't do anything, but I have no idea if there is something else that does the same thing or if it should just be omitted. Can you link some kind of syntax reference on your website or readme?
I agree. I had to scour the internet just to find out how to embed an image... Then i stumbled across a bug that disallows you to use any class name inside a filename because the url gets expanded to a link as well.
See my comment on #374.
I found the following on the markdown bits:
The library used: http://www.pell.portland.or.us/%7Eorc/Code/discount/ (can tomaz confirm this please?)
General markdown: http://daringfireball.net/projects/markdown/syntax
What's needed is a list of @name, @param, @available, @see etc and how each attribute is supported for toplevel objects versus methods (i browsed the sources and is not very consistent really - i can imagine tomaz doing a 3.0 rewrite).
I think it can be done in a few hours by just trying them out on a sample project.. What you think?
EDIT: I've written a 2-part blog post on installing and documenting code for beginners, the first one shows how to include appledoc in your build and the second one explains basic syntax.
Correct: appledoc uses Markdown syntax which was invented by John Gruber (aka Daring Fireball) and it's using Discount C library which parses the syntax and produces HTML. Essentially what appledoc does is a bit of preprocessing to convert various non-markdown elements into markdown (splitting the comment into components, handling cross refs etc).
Appledoc specific attributes are all implemented in comments processor class, but there are also additions that allow subset of headerdoc attributes; these are implemented elsewhere. It is messy and, again, regression-prone. I still have to bring general docs over to updated site, then I can include these as one of the articles.
Will link to your blog posts from appledoc homepage at http://gentlebytes.com/appledoc, thanks!
Molto grazie for the backlink and you're welcome.
I wrote up some notes which turned into an NSHipster article on working with appledoc: http://nshipster.com/documentation/
Seen it, thanks, nice piece, will link it from appledoc home once I get to it.
Did #400 take care of this, or is there still stuff missing from CommentsFormattingStyle.markdown?
There's still stuff missing, currently only available on wayback machine - click on links in sidebar on the right.