GNOME Bugzilla – Bug 313186
some discrepancy between documented funcs and exported symbols
Last modified: 2006-03-27 18:06:21 UTC
I notice that the following 30 functions have been added to at-spi since GNOME 2.0. The ones that should have documentation should be using the gtk-doc "Since:" tag to indicate what version they were added. AccessibleApplication_getLocale AccessibleBoundsChangedEvent_getNewBounds AccessibleEvent_ref AccessibleEvent_unref AccessibleStreamableContent_close AccessibleStreamableContent_freeContentTypesList AccessibleStreamableContent_getContentTypes AccessibleStreamableContent_open AccessibleStreamableContent_read AccessibleStreamableContent_ref AccessibleStreamableContent_seek AccessibleStreamableContent_unref AccessibleTextRange_freeRanges AccessibleText_getBoundedRanges AccessibleText_getDefaultAttributes AccessibleText_getRangeExtents Accessible_getLocalizedRoleName SPIAccessibleException_getSource SPIException_getDescription SPIException_getExceptionCode SPIException_getSourceType SPI_dupString SPI_exceptionHandlerPop SPI_exceptionHandlerPush SPI_freeRect _cspi_exception_throw cspi_object_take cspi_peek_ev cspi_streams_close_all get_streams I notice that the following functions are exported by at-spi, but do not contain gtk-docs. I suspect some of the functions (perhaps SPI_dupstring among others) shouldn't be exported at all. AccessibleApplication_getLocale AccessibleBoundsChangedEvent_getNewBounds AccessibleComponent_getAccessibleAtPoint AccessibleHyperlink_getIndexRange AccessibleStreamableContent_close AccessibleStreamableContent_freeContentTypesList AccessibleStreamableContent_getContentTypes AccessibleStreamableContent_open AccessibleStreamableContent_read AccessibleStreamableContent_ref AccessibleStreamableContent_seek AccessibleStreamableContent_unref AccessibleTable_addColumnSelection AccessibleTable_addRowSelection AccessibleTable_removeColumnSelection AccessibleTable_removeRowSelection AccessibleText_getCharacterAtOffset AccessibleText_getDefaultAttributes Accessible_getLocalizedRoleName SPIAccessibleException_getSource SPIException_getDescription SPIException_getExceptionCode SPIException_getSourceType SPI_dupString SPI_exceptionHandlerPop SPI_exceptionHandlerPush SPI_freeRect _cspi_exception_throw cspi_accessible_is_a cspi_check_ev cspi_device_listener_add_cb cspi_device_listener_get_corba cspi_device_listener_get_type cspi_device_listener_new cspi_device_listener_remove_cb cspi_device_listener_unref cspi_dup_ref cspi_ev cspi_event_listener_add_cb cspi_event_listener_get_corba cspi_event_listener_get_type cspi_event_listener_new cspi_event_listener_remove_cb cspi_event_listener_unref cspi_exception cspi_exception_get_text cspi_init cspi_main cspi_main_quit cspi_object_add cspi_object_borrow cspi_object_ref cspi_object_return cspi_object_take cspi_object_unref cspi_peek_ev cspi_ping cspi_registry cspi_release_unref cspi_streams_close_all get_streams
The docs and Since tags are there in the sources. What makes you think they are not? Are you sure you're looking at freshly built docs?
I was checking at-spi 1.6.3, and looking at CVS head it does seem that some of the docs are there (mainly the ones starting with Accessibility*). None of the cspi* functions have docs, cspi/spi_main.c has many "DOCUMENT_ME!" comments. Nothing in cspi/bonobo has docs. Also, grepping the source code, I don't see the "Since:" tag used once. As discussed in bug 313183, we should probably ignore the "*_get_type" functions since they probably don't need docs. But the other functions should be properly documented. Am I missing something? Also, I notice the following: Two global variables event_parent_class and device_parent_class defined in cspi/bonobo/cspi-bonobo-listener.c should probably be static and not exported in the library symbols.
Some of the undocumented methods, in particular the cspi_ methods, should be made internal if feasible. The only methods here which should be used by developers are the ones beginning with SPI* and those beginning with Accessible*. The 'Since' tag is mostly not relevant for cspi. The primary need for docs is in the IDL, where there is the problem that gtk-doc can't parse IDL. The current IDL is being edited so that doxygen gives useful docs. As such, the documentation of the idl is an enhancement.
This email list highlights the technique used by glib/GTK+ to use regular expressions to remove symbols that start with an underscore from the library. The same technique could be used to remove ones that begin with "cspi_" or other functions from the binary. http://mail.gnome.org/archives/gtk-devel-list/2001-January/msg00003.html If the functions are for internal-use only within the library itself, making them static functions might also make sense. When you say the 'Since' tab is mostly not relevant for cspi, what do you mean?
For reference, the new functions were added in the following versions: 1.3.11 AccessibleApplication_getLocale 1.5.3 AccessibleBoundsChangedEvent_getNewBounds 1.1.6 AccessibleEvent_ref 1.1.6 AccessibleEvent_unref 1.3.4 AccessibleStreamableContent_close 1.3.4 AccessibleStreamableContent_freeContentTypesList 1.3.4 AccessibleStreamableContent_getContentTypes 1.3.4 AccessibleStreamableContent_open 1.3.4 AccessibleStreamableContent_read 1.3.4 AccessibleStreamableContent_ref 1.3.9 AccessibleStreamableContent_seek 1.3.4 AccessibleStreamableContent_unref 1.1.9 AccessibleTextRange_freeRanges 1.1.8 AccessibleText_getBoundedRanges 1.3.9 AccessibleText_getDefaultAttributes 1.1.8 AccessibleText_getRangeExtents 1.3.9 Accessible_getLocalizedRoleName 1.3.3 SPIAccessibleException_getSource 1.3.3 SPIException_getDescription 1.3.3 SPIException_getExceptionCode 1.3.3 SPIException_getSourceType 1.3.3 SPI_dupString 1.3.3 SPI_exceptionHandlerPop 1.3.3 SPI_exceptionHandlerPush 1.5.3 SPI_freeRect
Created attachment 61933 [details] [review] patch to apply the Since tags where missing, except for pre-gnome-2.0 additions. Patch is ready to apply except for ChangeLog, and add'l documentation of four or five SPI* APIs which were marked DOCME! I plan to apply the completed patch on Monday.
Created attachment 62138 [details] [review] patch to strip symbols starting with "cspi", and add "Since" tag.