The new documentation does not show the return type of the functions in the documentation at all

[MichiB (Michael Buzgaru)]

Well, a better topic name I did not find out, sorry for that.

Earlier documentation showed the return type of the functions and I could easily sort them if I had, for example, to find out which functions returned gboolean or char*…and so on.

Now if I need to find out for example in the GtkWindow documentation which functions are returning let’s say gbooblean I cannot do that anymore because the return type is not listed anymore:

Why is that?
Is there an alternative of that ability to search only after a particularly return type?

Here is an example of GtkWindow

Here is an old documentation example, where the return type it is present.

[ebassi (Emmanuele Bassi)]

You’re literally searching for everything related to GtkWindow, instead of going to the GtkWindow class reference.

But, yes: the index does not list the full prototype, because that scales pretty badly when it comes to complex functions that take more than one argument, and makes the index page a lot more busy to visually scan for things; heavier to download on limited bandwidth; and harder to map to different languages, as the C API reference is used as a fallback by various bindings.

You should search for specific keywords, like “window title”, and then go to the method that you’re interested in, and see the full declaration.

@MichiB

Earlier documentation showed the return type of the functions and I could easily sort them if I had, for example, to find out which functions returned gboolean or char*…and so on.

How could you possibly “sort” functions in gtk-doc? The order in the list of declarations was hard coded by the author of the documentation, and the generated documentation had no search capabilities, and no way to go back to the list of declarations once you went to a specific function.

[MichiB (Michael Buzgaru)]

@ebassi

How could you possibly “sort” functions in gtk-doc?

There are many ways, but one which I use it in my scripts looks like this:

1)

lynx -dump https://developer-old.gnome.org/gtk2/stable/GtkWindow.html > gboolean.txt

2)

cat gboolean.txt | grep '()' | grep 'gboolean' | tr -d '0123456789[]''

Output, there you go:

gboolean gtk_window_get_resizable ()
gboolean gtk_window_activate_focus ()
gboolean gtk_window_activate_default ()
gboolean gtk_window_is_active ()
gboolean gtk_window_has_toplevel_focus ()
gboolean gtk_window_mnemonic_activate ()
gboolean gtk_window_activate_key ()
gboolean gtk_window_propagate_key_event ()
gboolean gtk_window_get_decorated ()
gboolean gtk_window_get_deletable ()
gboolean gtk_window_get_destroy_with_parent ()
gboolean gtk_window_get_has_frame ()
gboolean gtk_window_get_modal ()
gboolean gtk_window_get_skip_taskbar_hint ()
gboolean gtk_window_get_skip_pager_hint ()
gboolean gtk_window_get_urgency_hint ()
gboolean gtk_window_get_accept_focus ()
gboolean gtk_window_get_focus_on_map ()
gboolean gtk_window_has_group ()
gboolean gtk_window_parse_geometry ()
gboolean gtk_window_get_mnemonics_visible ()

[ebassi (Emmanuele Bassi)]

I’m sorry, but this is horrific.

If you want to go around the exposed API like a text file, you should use the introspection XML.

[MichiB (Michael Buzgaru)]

I am sorry that you find it horrific, but at least worked fine.

Please share with me, if there is a horrific way with the new Documentation?

PS: remember, I am doing YouTube videos on GTK and this was important for me.

[ebassi (Emmanuele Bassi)]

@MichiB

Please share with me, if there is a horrific way with the new Documentation?

Of course there isn’t, because that’s not something a documentation website is supposed to cater to or support.

You’re screen-scraping the HTML generated by a tool—which was the case even for the reference generated by gtk-doc—and you assume that a) it’s going to be stable across releases b) it’s going to be machine readable, and now you’re complaining that your screen-scraper is broken? Do you understand how that’s completely unsupportable?

@MichiB

PS: remember, I am doing YouTube videos on GTK and this was important for me.

I fail to understand the relevance of this statement.

The documentation website is geared towards people reading it, and finding how things work. It’s not designed for making it possible to be machine readable.

We already have a machine readable format that describes our API: it’s called gobject-introspection, and it’s what we use to generate the documentation, as well as language bindings. The format is stable, the output is stable, and it’s meant to be parsed by computers. You should use that.

[MichiB (Michael Buzgaru)]

@ebassi

Of course there isn’t, because that’s not something a documentation website is supposed to cater to or support.

But worked well, until you/they decided to change that.

@ebassi

and you assume that a) it’s going to be stable across releases b) it’s going to be machine-readable, and now you’re complaining that your screen-scraper is broken? Do you understand how that’s completely unsupportable?

I am definitely not assume that one at all, instead I have the feeling that YOU are somehow against my needs.

@ebassi

I fail to understand the relevance of this statement.

Of course, you do, my bad, you are not interested (you do not need) in learning GTK like some of us does.

Any way, that example there was only an explanation to your question:

How could you possibly “sort” functions in gtk-doc? 

and once that, you got it:

I’m sorry, but this is horrific.

And now you “fight” against it, by finding that one of my working solutions is bad.

I have the feeling that this discussion goes in the other direction.

[ebassi (Emmanuele Bassi)]

@MichiB

But worked well, until you/they decided to change that.

You cannot have any expectation that the generated HTML is going to be stable, even if we didn’t change the tool that generates the documentation.

@MichiB

And now you “fight” against it, by finding that one of my working solutions is bad.

My “it’s horrific” was directed to that particular “solution”.

I honestly care about people who want to read the documentation, not people who want to screen-scrape it; your script got broken because they were relying on something that was never meant to be relied upon—and I am not interested in catering to that particular use of our documentation.

If you want to do machine reading, we already offer you the tools and the file format for it. The documentation website is for human beings.

Yes, the documentation website has changed. The entire goal of the API reference is to present the API, and then let the reader “drill down” to specific pages; the documentation tool has stable, predictable links, and generates individual pages for each type, function, method, signal, property, etc. The index is not presenting the entire API for a page, or a bunch of symbols grouped together by some inscrutable criteria.

If you want to have a collection of C declarations, you should read the header files. If you want to search through the API using scripts, you should use the introspection data.

@MichiB

Of course, you do, my bad, you are not interested (you do not need) in learning GTK like some of us does.

This sarcasm is uncalled for, unless you seriously think I never use the API reference.

[MichiB (Michael Buzgaru)]

@ebassi

This sarcasm is uncalled for, unless you seriously think I never use the API reference.

It was a joke :))

@ebassi

You cannot have any expectation that the generated HTML is going to be stable, even if we didn’t change the tool that generates the documentation.

Of course, but my tool was working simple because I had to past the URL and Search_String as arguments and worked fine, and those URLs were never memorized inside the program at all.