GNOME Bugzilla – Bug 313183
atk doc not including "Since" tag in some new funcs
Last modified: 2006-06-28 14:44:24 UTC
I notice that the following 9 functions were added between GNOME 2.0 and 2.10, but the gtk-docs aren't using the "Since:" tag to indicate when these interfaces were added. This should be fixed. I also notice that the following functions are exported by the libatk library, but do not have docs. Not sure if the problem is that these functions should have docs, or should not be exported if they are for internal-use only. Probably the two atk_marshall* functions shouldn't be exported. atk_action_get_type atk_component_get_type atk_coord_type_get_type atk_document_get_type atk_editable_text_get_type atk_gobject_accessible_get_type atk_hyperlink_get_type atk_hyperlink_state_flags_get_type atk_hypertext_get_type atk_image_get_type atk_implementor_get_type atk_key_event_type_get_type atk_layer_get_type atk_marshal_VOID__INT_INT atk_marshal_VOID__STRING_BOOLEAN atk_no_op_object_factory_get_type atk_no_op_object_get_type atk_object_factory_get_type atk_object_get_type atk_rectangle_get_type atk_registry_get_type atk_relation_get_type atk_relation_set_get_type atk_relation_type_get_type atk_role_get_type atk_selection_get_type atk_state_set_get_type atk_state_type_get_type atk_streamable_content_get_type atk_table_get_type atk_text_attribute_get_type atk_text_boundary_get_type atk_text_clip_type_get_type atk_text_get_type atk_util_get_type atk_value_get_type
Oops, forgot to mention the 9 new functions: atk_get_focus_object atk_hyperlink_is_selected_link atk_rectangle_get_type atk_relation_add_target atk_relation_set_add_relation_by_type atk_text_clip_type_get_type atk_text_free_ranges atk_text_get_bounded_ranges atk_text_get_range_extents
Also, the following symbol is missing from the libgail-util docs: gail_text_util_get_type Lastly, in libatk I notice that the following symbols are being exported. I suspect these shouldn't be; device_parent_class event_parent_class
The new functions DO have gtk-docs in the sources. Are they not turning up in the html for some reason? The get_type stuff is always exported but never documented AFAIK, see the gtk+ docs for examples. Patch welcome if you check how gtk+ does this and follow suit here. Thanks!
Also, note that these docs DO include the 'Since:' keyword, see for instance atkrelation.c.
Sorry, let me clarify. 1) You are right, the get_type stuff doesn't have docs in any GNOME module. Not sure if this is right. I'll check on this and file a new bug if this is something we should address. 2) My comment about event_parent_class and device_parent_class are in error. The problem here is not in ATK but in libcspi in cspi/bonobo/cspi-bonobo-listener.c. I I think these two variables should be static and not exported. I'll add this to the cspi bug. Let's forget about this here. 3) The new functions are all properly documented aside from using the "Since" tag properly. You are right that two of the functions have been fixed since the 1.9.1 version I was checking. However the following still need "Since:" tags: atk_get_focus_object atk_hyperlink_is_selected_link atk_text_free_ranges atk_text_get_bounded_ranges atk_text_get_range_extents So, I think if we just add the Since tag to the above 5 functions, we should be okay.
For reference, the functions were added in these versions: atk_get_focus_object 1.5.1 atk_hyperlink_is_selected_link 1.3.0 atk_rectangle_get_type 1.7.2 atk_text_clip_type_get_type 1.9.1 atk_text_free_ranges 1.3.0 atk_text_get_bounded_ranges 1.3.0 atk_text_get_range_extents 1.3.0
Fixed in CVS. BTW this was NOT trivial to fix because of gtk-doc issues, and the need to double-check the version numbers above. The version numbers were very helpful, but in cases where the "first used version" was in the unstable branch, it was more appropriate to use the major/minor release for the first stable tarball instead.
Fixed in CVS. The fix will go into the next patch release. Thank you for your bug report.
I guess there is something more to do, because I don't see lists of new API for ATK here: http://developer.gnome.org/doc/API/2.0/atk/index.html GTK+ has this. See the end of this page: http://developer.gnome.org/doc/API/2.0/gtk/index.html I think I remember mclasen or someone saying once that some template must be changed to create these pages and the links to them.
This email seems to say how to do that: http://mail.gnome.org/archives/gtk-doc-list/2004-April/msg00011.html
Despite the fact that my /etc/xml/catalog file indicates that I have the 1.68.1 version of the xsl stylesheets, it's not working yet... I can commit the changes to the atk-doc.sgml template to add the indices, but at the moment they are empty. This seems to be because the xsl stylesheet for indices is much less forgiving than the gtk-doc stylesheets for the main pages, and thus it isn't parsing the strings correctly. Fixing it requires re-formatting the 'since' and 'deprecated' tags throughout the C sources in ATK.
> I can commit the changes That's probably a good idea. Then other people can try it too. > Fixing it requires re-formatting the 'since' and 'deprecated' tags throughout the C sources in ATK. Ah, so why can't we do that? I recommend regexxer for this. If you need help, please do ask on gtk-list. I know less about this than you do.
The carnage wasn't too bad, after all. Less than a half hour's work once I figured out what was required (which took most of the time). Fixed in CVS. However the 'new symbols' list doesn't include additions to various enums, since the gtk-doc stylesheet doesn't seem to find 'since' tags inserted there. Perhaps this should be a gtk-doc RFE, to allow 'Since' tags in enum docs?
BTW, thanks Murray for pointing me to the email which unblocked this work for me.
Many thanks. And this bug might help others trying to do the same thing.
About the enums, yes, I think that should be an RFE.
*** Bug 322033 has been marked as a duplicate of this bug. ***