Named sections of companion guides

[amyworrall]

I'm trying to convert someone's doxygen-marked-up code to use appledoc. It seems doxygen lets you give sections names, thus:

@section library The Library

Then when you want to refer to it, you can do

- @ref library, some more text here

And it automatically replaces @ref library with The Library, as well as providing a link to that section. The @section command also seems to make a section header.

This seems to be what I've been trying to describe in bug 84, but a more general case: from this documentation I see that doxygen allows @page, @section, @subsection and @subsubsection, and it uses all of these to generate different pages and link to the right bits.

I think that copying doxygen is the way to go here, unless there's a better idea floating around!

P.S. When I get some free time I'm going to try and have a look at the appledoc code. If I was able to make some changes myself it might make up for my many feature requests :)

[tomaz]

This is certainly doable. All these @ directives could simply create <a name="something" /> sections so should be relatively easy to link to them later on.

Hm, I wrote the comment for #85 and was suggesting similar thing, however looks like it was lost somehow (sometimes I manage to do stuff like that, just out of the blue :)
Anyway, this could also be used to close that issue!

[tomaz]

Just adding note and link to Amy's solution for future reference:

I've got sections in generated documents working (including displaying with the Apple-style sidebar). Code is at:

https://github.com/amyworrall/appledoc/

Sections are written as
@section shortname Human Readable Title

Also, documents themselves can be given a title via
@title Document Title

I haven't done anything for cross referencing yet. Eventually I'd like to have the section short name used for cross referencing: at the moment it fills in the tags with it, but that's it. However, I won't have time to implement that for a bit.

The code might need a little cleaning up. In particular in GBDocumentParser there's a check to see if someone tried to do a subsection outside a section, and I didn't know what to do if they did: at the moment I just NSLogged the error. I also haven't written any unit tests for the new functionality.

This is long overdue for bringing it into main branch, but I currently don't have time for it :)

[ryanjm]

Has there been any movement / updates on this?