After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 313183 - atk doc not including "Since" tag in some new funcs
atk doc not including "Since" tag in some new funcs
Status: RESOLVED FIXED
Product: atk
Classification: Platform
Component: docs
unspecified
Other opensolaris
: Low minor
: ---
Assigned To: bill.haneman
bill.haneman
: 322033 (view as bug list)
Depends on:
Blocks:
 
 
Reported: 2005-08-11 03:54 UTC by Brian Cameron
Modified: 2006-06-28 14:44 UTC
See Also:
GNOME target: ---
GNOME version: ---



Description Brian Cameron 2005-08-11 03:54: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
Comment 1 Brian Cameron 2005-08-11 03:55:00 UTC
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
Comment 2 Brian Cameron 2005-08-11 06:16:15 UTC
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
Comment 3 bill.haneman 2005-08-11 09:18:54 UTC
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!

Comment 4 bill.haneman 2005-08-11 09:20:03 UTC
Also, note that these docs DO include the 'Since:' keyword, see for instance
atkrelation.c.
Comment 5 Brian Cameron 2005-08-11 16:07:11 UTC
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.
Comment 6 Brian Cameron 2005-08-16 05:32:11 UTC
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

Comment 7 bill.haneman 2006-03-31 09:24:08 UTC
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.
Comment 8 bill.haneman 2006-03-31 09:35:16 UTC
Fixed in CVS. The fix will go into the next patch release. Thank you for your bug report.
Comment 9 Murray Cumming 2006-06-23 13:35:56 UTC
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.
Comment 10 Murray Cumming 2006-06-23 13:36:51 UTC
This email seems to say how to do that:
http://mail.gnome.org/archives/gtk-doc-list/2004-April/msg00011.html
Comment 11 bill.haneman 2006-06-23 15:28:59 UTC
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.

Comment 12 Murray Cumming 2006-06-23 15:35:11 UTC
> 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.
Comment 13 bill.haneman 2006-06-23 16:04:08 UTC
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?
Comment 14 bill.haneman 2006-06-23 16:05:42 UTC
BTW, thanks Murray for pointing me to the email which unblocked this work for me.
Comment 15 Murray Cumming 2006-06-23 19:08:13 UTC
Many thanks. And this bug might help others trying to do the same thing.
Comment 16 Murray Cumming 2006-06-23 19:08:49 UTC
About the enums, yes, I think that should be an RFE.
Comment 17 bill.haneman 2006-06-28 14:44:24 UTC
*** Bug 322033 has been marked as a duplicate of this bug. ***