Add a full syntax reference #376

mrosales opened this Issue Jul 22, 2013 · 9 comments


None yet

5 participants

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.

tomaz commented Jul 25, 2013

See my comment on #374.


I found the following on the markdown bits:

The library used: (can tomaz confirm this please?)
General markdown:

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.

tomaz commented Jul 29, 2013

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, thanks!


Molto grazie for the backlink and you're welcome.

orta commented Aug 9, 2013

I wrote up some notes which turned into an NSHipster article on working with appledoc:

tomaz commented Aug 9, 2013

Seen it, thanks, nice piece, will link it from appledoc home once I get to it.

mkantor commented Feb 11, 2014

Did #400 take care of this, or is there still stuff missing from CommentsFormattingStyle.markdown?

tomaz commented Feb 12, 2014

There's still stuff missing, currently only available on wayback machine - click on links in sidebar on the right.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment