Re: gtk-doc and gobject introspection

[Stefan Kost <ensonic hora-obscura de>]

On 08/10/11 00:33, Florian Brosch wrote:
> 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.
Maybe we can solve the library.gnome.org interation by having diferent
css files.

> 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
I hope that we can get rid of them in the long run by having the
annotation there instead.
> 3. Unnamed source examples are forcing us to replace the whole comment
> instead of the necessary part
the examples should be enclosed in |[ example ]| markers. This
unfortunately lacks a syntax to specify the language contained. Even for
c-doc this could be shell-script or xml.
> 4. Some referred pages are not part of gir.
Yes git scanner does not know of the main.xml file and the included
extra docs.
> 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.
>
That unfortunately won't work. The gir scanner takes the text blobs from
the sources. I handle the markdown parts in gtkdoc-mkdb which transforms
the extracted comment blobs into docbook xml.

Stefan