GNOME Bugzilla – Bug 136505
improving DocsParser.pm to support method mappings
Last modified: 2004-12-22 21:47:04 UTC
OK, this is just a first glance at the functionality. 1) The idea is to change the policy of the DocsParser. At the moment it reads the docs.xml file and builds a hashed list of all functions described inside. After thatit reads the docs_override.xml file. Everytime it encounters a function name already in the hashlist (read from docs.xml) it completely deletes all information stored for that function and builds a new entry, now containing only data from the docs_override.xml. I changed this so the parser now only changes the data that really is newly set in the docs_override.xml. docs.xml: <function name="somefunction"> <description>Function's description.</description> <return>Returns some value</return> </function> docs_override.xml: <function name="somefunction"> <description>A new description</description> </function> This fragment results in a function "somefunction" with the description "A new description" and the return "Returns some value". So only the description is overridden by the docs_override.xml. 2) I added a new tag named <mapping>. it has no cdata content and supports the property class="...". doc_override.xml: <function name="somefunction"> <mapping class="Style"> </function> This definition maps the function "somefunction" into the class "Style". Actually it just says "this function belongs to a class" so the outputter knows it has to drop the first parameter from the parameter list (as it is the pointer to the object [in gtk]) 1) + 2) To make this clear once more. There is no need for two declarations as above. docs_override.xml now MAY look like this (though it is not a MUST, it MAY also contain two declarations): <function name="somefunction"> <description>A new description</description> <mapping class="Style"> </function> Which achives the cumulative result from 1) and 2). function = "somefunction" description = "A new description" return = "Returns some value" mapping = Style 3) There is one addition to the regular expressions at the end of the file. It allows names to contain numbers like x1, x2, y1, y2 in gdk/gdkmm/region.h. We have to take a second look at this regexp ... it does NOT do what it promises: the trailing underscore from index_ is not removed. (see gtk/gtkmm/treemodel.h:303)
Created attachment 25309 [details] [review] Attempts to fix some gmmproc misbehavior
1) I'm not sure that this is a good idea, because it makes it impossible to use gtk_overrides.xml to remove something - for instance, to remove any return type. But that is not actually needed, so OK. 2) I would prefer "of-object" to "mapping". That's more like the .defs file format. I think it should mention the C typename, such as GtkStyle instead of a C++ class, because these are C docs for C functions. 3) So this is not a regression? Could you revise the patch for 2) - then I will commit it.
1) Actually this is possible. Even better than before: docs_overrides.xml: <function name="somefunction"> <return></return> </function> does exactly the job. Even better because it leaves the description and the parameter list untouched. This wouldn't be possible without the patch. You'd have to rewrite the complete entry from docs.xml (except the return) 2) I can understand your argument, however I would like to say this: docs_overrides.xml is exactly NOT to describe C functions. docs_overrides.xml is the step from C to C++. If we'd make docs_overrides.xml contain C++ documentation it also could be used to describe overloaded functions, constructors, destructors and so on. Well, just my 5 pence, just say: "no" and I will make it like so: <of-object object="GtkStyle" /> 3) No. This didn't work before either. Look at your doxygen-warnings.txt file it contains warnings about these trailing underscores. This update just addresses the numbers.
Yeah, OK. Committed.