API docs for libunity

[Mikkel Kamstrup Erlandsen]

We need to somehow generate API docs for libunity. We want us (and others) to be able to code in C as well as Vala, Python and what have we...

[Mikkel Kamstrup Erlandsen (kamstrup)]

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

[David Barth (dbarth)]

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

[Neil J. Patel (njpatel)]

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

[Daniele "OpenNingia" Simonetti (oppifjellet)]

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.

[Marco Trevisan (Treviño) (3v1n0)]

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/

[Michal Hruby (mhr3)]

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.)

[Mikkel Kamstrup Erlandsen (kamstrup)]

@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?

[Michal Hruby (mhr3)]

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.