Re: gtk-doc and gobject introspection

[Florian Brosch <flo brosch gmail com>]

Hi again,


> 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 think it is enough to mark memory management information at C-level
and to demand people to name their code examples.

That should allow us to handle almost all language specific cases easily.


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

We are still using native doc tools to document gnome relevant
libraries and applications. How do they fit in your plan?

How are you planning to make them work together? How are we inheriting
documentation? How are we referring from native written code to our
fully documented nodes generated by our gtk-doc output?

How are python/mono/perl/etc-documentation-provider supposed to embed
gtk-doc into their libraries?

How are IDEs supposed to use our gtk-doc generated documentation? Is
there anyone around who cares enough to add support to common tools?

Mono has its own documentation browser and an xml-based documentation format.

What about unbounded symbols? How do we know them on gtkdoc-level? How
are we handling links to them? Are binding-developers supposed to
provide meta data to handle this issue?

What about functions that are bounded in two different ways?

What about utility functions added on binding-level?

Not all bindings are using gir.

etc.

We are creating new problems here and pushing them away to people who
are trying to integrate the gnome-platform in different languages that
way instead of helping them to integrate it as well as possible. I
honestly think that's the wrong approach.


However, we could add new backends to common documentation tools to
get the same output for all languages without loosing all the benefits
we get by using native documentation stacks.

The list of languages we are currently supporting / linking on
developer.gnome.org isn't that long:

 - Python (?)
 - Java (javadoc)
 - Vala (valadoc)
 - C++ (doxygen)

I'm willing to provide plugins for valadoc and javadoc.

Doxygen does not provide a plugin interface as far as I know. But it
is able to create a bunch xml-files including all the information we
need.

> 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

I worked on extracting the docs for vala last week. The current
approach is simple and efficient.

Here are all issues I found:

1. We do not know the c-name of our this-parameter.
2. There is no elegant way to get rid of memory management descriptions
3. Unnamed source examples are forcing us to replace the whole comment
instead of the necessary part
4. Some referred pages are not part of gir.

There is no demand on duplicating some parts of our binding generators
on gtk-doc level just to provide good binding-documentation.


> (e.g. highlight when c-docs changed to notify them that
> they might want to review the same part in the bindings docs).

That could be done with xquery easily. I like the idea.


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

Sounds good to me. What do you think about transforming it into xml at
gir-level on long term? That should allow us to pick up the
documentation easily.


On Mon, Aug 8, 2011 at 10:18 AM, Stefan Kost <ensonic hora-obscura de> wrote:
> 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
>>>
>
>