Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Add a full syntax reference #376

Open
mrosales opened this Issue · 9 comments

5 participants

@mrosales

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?

@robvdveer
Collaborator

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
Owner

See my comment on #374.

@robvdveer
Collaborator

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
Smartypants: http://daringfireball.net/projects/smartypants/

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
Owner

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!

@robvdveer
Collaborator

Molto grazie for the backlink and you're welcome.

@orta

I wrote up some notes which turned into an NSHipster article on working with appledoc: http://nshipster.com/documentation/

@tomaz
Owner

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

@mkantor

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

@tomaz
Owner

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
Something went wrong with that request. Please try again.