Re: gtk-doc and gobject introspection

[Florian Brosch <flo brosch gmail com>]

Hi Stefan,

I think you are underestimating the amount of work on generating
signatures out of gir-files for different languages. We need a ton of
meta data to generate vapis out of gir files in vala-land for
instance. [1][2]

We also can't reuse C-documentation for other languages all the time.
Basic examples are memory management, source code examples and
references to hidden symbols.

I also think it's a better approach to use the output format people
are used to in the language of their choice. It's simpler for them to
find information and simpler for IDE developer who are supporting
documentation lookup.

So my main questions are: What are you trying to achieve? What are the
advantages?


The better approach is to improve the way documentation is embedded in
gir files by replacing gtk-doc specific particulars like
functionname() and %CONSTANT with the equivalent docbook tags and by
allowing docbook in doc-elements directly instead of escaping them.


Flo

[1] http://git.gnome.org/browse/vala/tree/vapi/metadata
[2] http://git.gnome.org/browse/pygobject/tree/gi/overrides


On Sun,  Aug 7, 2011 at 14:27 AM, Stefan Kost <ensonic hora-obscura de> wrote:
> Hi,
>
> with all the cool things happening around gobject-introspection it would
> be cool to come up with a strategy for the api-docs. I've been writing
> up things on lgo wiki:
>
> https://live.gnome.org/DocumentationProject/GtkDocLanguageBindings
> https://live.gnome.org/DocumentationProject/GtkDocGir
>
> I am curious what people think about it, what are the things I am
> missing, what are the expectations for people on api-docs for language
> bindings. Lets discuss how to do it. What are the steps to take, how to
> do the transition, ...
>
> Stefan
>