API docs for libunity

Current plan is to keep it simple by using valadoc, but there's no real progress yet though

Still applicable to the new version, though not as urgent if the Places API is already up and public.

Is there no way of getting vala to keep the comments? Seems like a reasonable feature request?

What I understand is that the C code is automatically generated from the Vala one and this "generator" is stripping the comments.
Am I right?

If that's the case I don't believe that keeping the [Vala] comments is the solution, because C is a different language and vanilla comments, if not properly translated, wouldn't be of any uses.

This is more clear if you imagine a function documentation with a code example; a Vala code sample in a C library documentation won't make any sense.

valac shouldn't strip the gtk-doc comments (the ones starting with /** ...).
When they are formatted using the correct syntax, rest on the .c files (it actually happens for any libunity/src/unity-*.c !) and so it's possible to use the proper tools to generate the documentation like for any project written in C.

Otherwise there's also another tool called valagtkdoc [1] that could help.

[1] http://lethalman.hostei.com/valagtkdoc/

The entire G* stack is moving to generating documentation from the .gir files that are produced by g-ir-scanner, and there's support in valadoc to output gir with the documentation tags, so we'll use this approach. (the final documentation can then be generated from .gir using g-ir-doc-tool, and if that isn't mature enough we can keep using giraffe.)

@Michal, you should coordinate with Kevin Wright. He might be looking at similar prospects. Wrt g-ir-doc-tool, I am all for supporting whatever upstream GI choose, but last I checked, and what I hear as well, was that development on it stagnated?

Marking this as fixed, as libunity finally has now a proper support for valadoc, which can generate standard gtk-doc as well as documented .gir file.

Of course there's still the issue that we have very few doc comments in the sources, but that's a different bug.