Re: gtk-doc and gobject introspection

[Stefan Kost <ensonic hora-obscura de>]

Hi Florian,
On 08/08/11 00:24, Florian Brosch wrote:
> 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]
Be assured, I am not underestimating it. I am aware of a lot of
problems, but you'll have to start somewhere. Thatnks for the metadata
pinters. I'll have a look.

> 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 was thinking of a i18n like approach as one options. Like we do for
user-manuals. Instead of 'fr' or 'de' you will have 'python', 'perl' and
'vala' :)
> 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.
Personally I'd like to have all api-docs in the same style for
consistency. Also gtk-doc + devhelp already has he mechanisms to switch
between languages and show you the relevant docs.
> So my main questions are: What are you trying to achieve? What are the
> advantages?
Right now with gobject introspection we can generate bindings for
several languages but missing the relevant docs. There are definitely
parts that needs to be written by people, but there are also things that
can be generated or at least ways to support the people that document
the bindings (e.g. highlight when c-docs changed to notify them that
they might want to review the same part in the bindings docs).
> 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.
Personaly I don't want to force people to write docbook into their docs.
The last gtk-doc release has a bit of markdown support also for better
readability in the sources. Also ideally I'd like to kill the whole
docbook processing as it is slow beyond easy fixability and also no one
is really working on the tools.

Thanks for your comments!

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