API docs for libunity

Bug #589091 reported by Mikkel Kamstrup Erlandsen on 2010-06-03
This bug affects 7 people
Affects Status Importance Assigned to Milestone
Fix Released
Michal Hruby
libunity (Ubuntu)

Bug Description

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

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

affects: anjali → unity
Mirco Müller (macslow) on 2010-07-02
Changed in unity:
milestone: none → 2010-07-08
assignee: nobody → Mikkel Kamstrup Erlandsen (kamstrup)
importance: Undecided → Low
status: New → Triaged
Neil J. Patel (njpatel) on 2010-07-12
Changed in unity:
milestone: 2010-07-08 → 2010-07-29
David Barth (dbarth) on 2010-07-27
Changed in unity:
milestone: 2010-07-29 → backlog
David Barth (dbarth) wrote :

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

Changed in unity:
assignee: Mikkel Kamstrup Erlandsen (kamstrup) → nobody
milestone: backlog → none
tags: added: backlog
Neil J. Patel (njpatel) wrote :

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

Changed in unity:
milestone: none → 3.4
assignee: nobody → Mikkel Kamstrup Erlandsen (kamstrup)
milestone: 3.4 → none
visibility: private → public
Changed in libunity:
status: New → Triaged
importance: Undecided → High
assignee: nobody → Mikkel Kamstrup Erlandsen (kamstrup)
David Planella (dpm) on 2011-02-11
tags: added: developer-portal-api-docs

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.

Didier Roche (didrocks) on 2011-02-21
Changed in libunity (Ubuntu):
status: New → Triaged
Didier Roche (didrocks) on 2011-05-31
Changed in unity-2d:
status: New → Triaged

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) wrote :

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

Changed in libunity:
assignee: Mikkel Kamstrup Erlandsen (kamstrup) → Michal Hruby (mhr3)
description: updated

@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) wrote :

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.

no longer affects: unity-2d
no longer affects: unity
Changed in libunity:
status: Triaged → Fix Committed
milestone: none → 6.8.0
Changed in libunity:
status: Fix Committed → Fix Released
To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Duplicates of this bug

Other bug subscribers