can you attach a diff between the docs generated with the old script and docs generated by your script so we can get a feel for what problem is actually being solved here?

Created attachment 150933 [details]
Difference between generated xml doc files

Here's a (compressed) diff of the two generated xml doc files for gstreamermm.  The original xml is generated as always, the second with the attached script.

I just noticed that there is a slight difference in the output of the <return></return> tags so the script could probably be modified to do what is normally done in that case.

I'll attach a diff for glibmm later (if it is needed).

Also the output of the function mentioned in the bug referenced in the original report looks like the following (the output can be compared with what is reported in the bug):

<function name="gst_mixer_list_tracks">
<description>
Returns a list of available tracks for this mixer/element. Note
that it is allowed for sink (output) elements to only provide
the output tracks in this list. Likewise, for sources (inputs),
it is allowed to only provide input elements in this list.

</description>
<parameters>
<parameter name="mixer">
<parameter_description> the #GstMixer (a #GstElement) to get the tracks from.
</parameter_description>
</parameter>
</parameters>
<return>
A #GList consisting of zero or more #GstMixerTracks.
The list is owned by the #GstMixer instance and must not be freed
or modified.
</return>
</function>

I think that the functions with names starting with uppercase in the original xml are attempts at generating signal docs (I'm not sure).  The attached script generates signal xml like the following if desired (via a specified switch):

<signal name="GstBin::element-added">
<description>
Will be emitted after the element was added to the bin.
</description>
<parameters>
<parameter name="bin">
<parameter_description> the #GstBin
</parameter_description>
</parameter>
<parameter name="element">
<parameter_description> the #GstElement that was added to the bin
</parameter_description>
</parameter>
</parameters>
<return>
</return>
</signal>

I kind of see the xml as being used for signal docs in the future if it is possible.  Of course, the xml can be refined if necessary.

The script also generates property xml, but I think that properties already have a way of being documented:

<property name="GstBin:async-handling">
<description>
If set to #TRUE, the bin will handle asynchronous state changes.
This should be used only if the bin subclass is modifying the state
of its children on its own.

Since: 0.10.13
</description>
</property>

Right now, the script is designed to process *.c files so I didn't think of generating docs for enums, but if *.h files are also processed, I think that enum docs can also be generated fairly easily so I'll try to add that and attach a substitute patch if the script promises usefulness.

I only submit this in case it does have some use. You, the glibmm maintainers would determine that.

Created attachment 150957 [details] [review]
gstreamermm difference between generated functions

Created attachment 150958 [details] [review]
glibmm difference between generated functions

Here's a difference of the glibmm generated functions.  I could not provide a difference of the xml because the sorting of it failed due to some &..; being interpreted as tags by the sorter I'm using.

Created attachment 150960 [details] [review]
Updated patch now with enum processing.

This patch is updated to include enum xml.  One thing to consider is whether it is convenient to accept source files to be processed directly on the command line or whether to allow directories and search for source files in them instead.

Created attachment 151012 [details] [review]
Updated patch to allow the same processing for lines in comment blocks without preceding asterisks

Updated according to the description.  Also added output confirming file processing.  There is no difference in the xml output except that lines without preceding asterisks in comment blocks are processed as part of the comment block regardless.

So is this a drop-in replacement for docextract_to_xml.py? Should we start using it now?

Of course, I'd rather fix the original python script rather than have a completely new script.

It should be a drop in replacement, except that it doesn't process files in the tmpl/ directories because the gtk-doc manual suggests that these files not be used anymore.  Having looked at the docextract_to_xml.py code, it seems better because it does the processing by directories instead of by files.

I'm in the process of seeing how the features in this tool (like property and signal xml) can be included in the original script and then this tool will not be needed.  In the meanwhile, if it's okay, this can remain open.  I'd rather keep it open to remind me that the transition needs to be done.

If bug #615136 is accepted, this one can be closed because the enhancements in the patch in that bug implement most of what is implemented here (except for enum handling because the python doc extraction scripts process just *.c files).

Bug #615136 has been accepted and resolved.  The python doc generation tool essentially now does what this tool would have done and more because it also handles GObject Introspection annotations.  Closing this enhancement request as obsolete.