Generate documentation metadata files for rustdoc-stripper

[gkoz]

As a first step, copy the documentation from the GIRs altering the formatting to make rustdoc happy (change %FOO or @FOO, etc. to FOO). Apply more processing to taste.

The next goal is having a toml or something with hand-written docs overrides.

[GuillaumeGomez]

I'd like to work on this.

[gkoz]

For the record, since opening this issue the docs were pulled into external files so the goal now is to generate a documentation metadata file that could be used as input for rustdoc-stripper, which would embed the docs into the code.

[GuillaumeGomez]

Where is stored documentation? I didn't find it in the gtk-rs Gir.toml file. Where can I get it from?

[gkoz]

The documentation strings, like everything else, come from the girs. Here's a fragment of Gtk-3.0.gir

      <constructor name="new"
                   c:identifier="gtk_about_dialog_new"
                   version="2.6">
        <doc xml:space="preserve">Creates a new #GtkAboutDialog.</doc>
        <return-value transfer-ownership="none">
          <doc xml:space="preserve">a newly created #GtkAboutDialog</doc>
          <type name="Widget" c:type="GtkWidget*"/>
        </return-value>
      </constructor>

The doc elements of the function and its return value are of interest here.

(1) Getting to them will involve adding relevant fields to various library structs (Class, Record, Function, Parameter, and so on) and teaching the parser to read them.

(2) There needs to be a module responsible for transformations, e.g. changing #GtkAboutDialog to AboutDialog.

(3) A new generator mode doc could then take the data from (1), apply (2) and write it to a "cmts" file.