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 _______________________________________________ desktop-devel-list mailing list desktop-devel-list@gnome.org http://mail.gnome.org/mailman/listinfo/desktop-devel-list