GNOME Bugzilla – Bug 791928
gtk-doc doesn't understand '@stability: Obsolete'
Last modified: 2018-01-08 20:04:36 UTC
File libanjuta/interfaces/libanjuta.idl uses '@stability: Obsolete' in 'SECTION:ianjuta-buildable'. causing the python2 version of gtkdoc-mkdb to crash. The documentation can be successfully built if I remove '@stability: Obsolete'. gmake[4]: Entering directory '/home/lantw44/gnome/build/anjuta/manuals/reference/libanjuta' DOC Building XML /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-cell-renderer-captioned-image.c:28: warning: Section cell-renderer-captioned-image is not defined in the libanjuta-sections.txt file. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-dock.c:36: warning: Section AnjutaDock is not defined in the libanjuta-sections.txt file. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-command-bar.c:335: warning: Parameter description for anjuta_command_bar_get_action_group::self is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaCommandQueueExecuteMode are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-completion.c:85: warning: Parameter description for anjuta_completion_complete::max_completions is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-debug.h:51: warning: Parameter description for DEBUG_PRINT::format is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-debug.h:51: warning: Parameter description for DEBUG_PRINT::... is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-dock.c:298: warning: Parameter description for anjuta_dock_remove_pane::self is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-language-provider.c:300: warning: Parameter description for anjuta_language_provider_get_pre_word::word_characters is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-language-provider.c:250: warning: Parameter description for anjuta_language_provider_get_calltip_context::lang_prov is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaLauncherOutputType are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-plugin-description.c:591: warning: Parameter description for anjuta_plugin_description_new_from_string::error is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-preferences.c:245: warning: Parameter description for anjuta_preferences_register_all_properties_from_builder_xml::settings is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-profile.h:62: warning: Value description for AnjutaProfileError::ANJUTA_PROFILE_ERROR_PLUGIN_MISSING is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaProjectValueType are missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaProjectPropertyFlags are missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaProjectNodeType are missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaProjectNodeState are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.h:189: warning: Parameter description for AnjutaProjectNodeForeachFunc::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:214: warning: Parameter description for anjuta_project_node_root::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:201: warning: Parameter description for anjuta_project_node_parent::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:232: warning: Parameter description for anjuta_project_node_first_child::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:246: warning: Parameter description for anjuta_project_node_last_child::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:265: warning: Parameter description for anjuta_project_node_next_sibling::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:278: warning: Parameter description for anjuta_project_node_prev_sibling::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:291: warning: Parameter description for anjuta_project_node_nth_child::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:291: warning: Parameter description for anjuta_project_node_nth_child::n is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:493: warning: Parameter description for anjuta_project_node_parent_type::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:493: warning: Parameter description for anjuta_project_node_parent_type::type is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:446: warning: Parameter description for anjuta_project_node_foreach::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:446: warning: Parameter description for anjuta_project_node_foreach::order is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:446: warning: Parameter description for anjuta_project_node_foreach::data is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:470: warning: Parameter description for anjuta_project_node_children_foreach::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:470: warning: Parameter description for anjuta_project_node_children_foreach::data is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:359: warning: Parameter description for anjuta_project_node_traverse::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:359: warning: Parameter description for anjuta_project_node_traverse::order is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:359: warning: Parameter description for anjuta_project_node_traverse::data is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:383: warning: Parameter description for anjuta_project_node_children_traverse::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:383: warning: Parameter description for anjuta_project_node_children_traverse::data is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:721: warning: Parameter description for anjuta_project_node_append::parent is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:721: warning: Parameter description for anjuta_project_node_append::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:710: warning: Parameter description for anjuta_project_node_prepend::parent is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:710: warning: Parameter description for anjuta_project_node_prepend::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:765: warning: Parameter description for anjuta_project_node_get_file::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:801: warning: Parameter description for anjuta_project_node_get_properties_info::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:812: warning: Parameter description for anjuta_project_node_get_properties::node is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-project.c:1339: warning: Parameter description for anjuta_project_node_info_new::type is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaSerializerMode are missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaSessionPhase are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-shell.h:50: warning: Value description for AnjutaShellError::ANJUTA_SHELL_ERROR_DOESNT_EXIST is not used from source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-shell.h:50: warning: Value descriptions for AnjutaShellError are missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaShellPlacement are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-status.c:624: warning: Parameter description for anjuta_status::status is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-status.c:624: warning: Parameter description for anjuta_status::mesg is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-status.c:624: warning: Parameter description for anjuta_status::timeout is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaTokenType are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-ui.c:1077: warning: Parameter description for anjuta_ui_add_toggle_action_group_entries::can_customize is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-ui.c:1115: warning: Parameter description for anjuta_ui_add_action_group::can_customize is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/anjuta-utils.c:2493: warning: Parameter description for anjuta_util_builder_get_objects::... is missing in source code comment block. unknown:0: warning: Value descriptions for AnjutaVcsStatus are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/e-splash.c:187: warning: Parameter description for e_splash_construct::progressbar_position is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/e-splash.c:229: warning: Parameter description for e_splash_new::progressbar_position is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-buildable.h:55: warning: Value description for IAnjutaBuildableCommand::IANJUTA_BUILDABLE_COMMAND_AUTORECONF is missing in source code comment block. ianjuta-buildable:31: warning: Section stability level is Obsolete.It should be one of these: Stable, Unstable, or Private. unknown:0: warning: Field descriptions for struct IAnjutaDebuggerMemoryBlock are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-editor.c:695: warning: Parameter description for ianjuta_editor_set_auto_indent::err is missing in source code comment block. unknown:0: warning: Field descriptions for struct IAnjutaEditorAssistProposal are missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-editor-cell.c:80: warning: Parameter description for ianjuta_editor_cell_get_char::char_index is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-editor-hover.c:53: warning: Parameter description for ianjuta_editor_hover_display::position is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-editor-search.c:57: warning: Parameter description for ianjuta_editor_search_backward::case_sensitive is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-editor-search.c:86: warning: Parameter description for ianjuta_editor_search_forward::case_sensitive is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-environment.h:45: warning: Value description for IAnjutaEnvironmentError::IANJUTA_ENVIRONMENT_CONFIG is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-environment.h:45: warning: Value description for IAnjutaEnvironmentError::IANJUTA_ENVIRONMENT_OTHER_ERROR is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-environment.h:45: warning: Value description for IAnjutaEnvironmentError::IANJUTA_BUILDER_CONFIG is not used from source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-environment.h:45: warning: Value description for IAnjutaEnvironmentError::IANJUTA_BUILDER_OTHER_ERROR is not used from source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-language.c:143: warning: Parameter description for ianjuta_language_get_make_target::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-language.c:164: warning: Parameter description for ianjuta_language_get_mime_types::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-language.c:187: warning: Parameter description for ianjuta_language_get_name::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-language.c:233: warning: Parameter description for ianjuta_language_get_strings::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-plugin-factory.h:61: warning: Value description for IAnjutaPluginFactoryError::IANJUTA_PLUGIN_FACTORY_OK is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-provider.c:74: warning: Parameter description for ianjuta_provider_get_name::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol.h:78: warning: Value description for IAnjutaSymbolField::IANJUTA_SYMBOL_FILED_SCOPE_DEF_ID is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol.h:78: warning: Value description for IAnjutaSymbolField::IANJUTA_SYMBOL_FIELD_SCOPE_DEF_ID is not used from source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol-manager.c:56: warning: Parameter description for ianjuta_symbol_manager_activate_package::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol-manager.c:84: warning: Parameter description for ianjuta_symbol_manager_add_package::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol-manager.c:133: warning: Parameter description for ianjuta_symbol_manager_deactivate_all::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-symbol-manager.c:157: warning: Parameter description for ianjuta_symbol_manager_deactivate_package::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.h:47: warning: Value description for IAnjutaVcsError::IANJUTA_VCS_UNKOWN_ERROR is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.h:47: warning: Value description for IAnjutaVcsError::IANJUTA_VCS_UNKNOWN_ERROR is not used from source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.c:53: warning: Parameter description for ianjuta_vcs_add::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.c:79: warning: Parameter description for ianjuta_vcs_checkout::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.c:106: warning: Parameter description for ianjuta_vcs_diff::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.c:134: warning: Parameter description for ianjuta_vcs_query_status::err is missing in source code comment block. /home/lantw44/gnome/source/anjuta/libanjuta/interfaces/ianjuta-vcs.c:159: warning: Parameter description for ianjuta_vcs_remove::err is missing in source code comment block. ./libanjuta-unused.txt:1: warning: 50 unused declarations. They should be added to libanjuta-sections.txt in the appropriate place. Traceback (most recent call last):
+ Trace 238288
mkdb.Run(options)
OutputAnnotationGlossary()
for annotation in sorted(iterkeys(AnnotationsUsed), key=str.lower):
Thank you for reporting this. I have checked too that it is working when using python3 instead of python2. In the documentation, it's only written that it is recommended to use predefined stability levels, so using obsolete is not wrong even if it emits a warning. I think it is rather a bug in gtk-doc, that shouldn't crash in this case. I suppose it could be fixed by changing the ParseStabilityLevel function to return a string object when the warning is emitted.
Hmm, two things: 1) I don't see any fancy unicode characters in '@stability: Obsolete'? I'll try locally. 2) '@stability: Obsolete' is not an annotation. Can you please post the whole comment block here or link to it?
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #2) > 1) I don't see any fancy unicode characters in '@stability: Obsolete'? There is no unicode characters here. I suppose anjuta source code is read as an unicode string and as 'Obsolete' isn't a standard annotation, it is not replaced by an ascii string like 'Stable', 'Unstable' ... > 2) '@stability: Obsolete' is not an annotation. According to this document https://developer.gnome.org/gtk-doc-manual/unstable/documenting_sections.html It seems that it's possible to use other names. The standard names are only recommended. > Can you please post the whole comment block here or link to it? Which code, the one in Anjuta? libanjuta/interfaces/ianjuta-buildable.c: line 28 /** * SECTION:ianjuta-buildable * @title: IAnjutaBuildable * @short_description: Implemented by plugins that can build. This interface * will be replaced by #IAnjutaBuilder (for build functions) and * #IAnjutaEnvironment for ianjuta_buildable_set_command, * ianjuta_buildable_reset_command and ianjuta_buildable_get_command. * @see_also: * @stability: Obsolete * @include: libanjuta/interfaces/ianjuta-buildable.h * */
(In reply to Sébastien Granjoux from comment #3) > (In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #2) > > Can you please post the whole comment block here or link to it? > > Which code, the one in Anjuta? > > libanjuta/interfaces/ianjuta-buildable.c: line 28 > /** > * SECTION:ianjuta-buildable > * @title: IAnjutaBuildable > * @short_description: Implemented by plugins that can build. This interface > * will be replaced by #IAnjutaBuilder (for build functions) and > * #IAnjutaEnvironment for ianjuta_buildable_set_command, > * ianjuta_buildable_reset_command and ianjuta_buildable_get_command. > * @see_also: > * @stability: Obsolete > * @include: libanjuta/interfaces/ianjuta-buildable.h > * > */ Yes, but libanjuta/interfaces/ianjuta-buildable.c is a generated file. The source code of this section is in libanjuta/interfaces/libanjuta.idl, line 847.
Hmm, the code only allows {Stable|Unstable|Private} https://git.gnome.org/browse/gtk-doc/tree/gtkdoc/mkdb.py#n2062 Anyway, this should fix it. Commit 2009441628aab105ffc7d002f1c0a64c184d1f84 (HEAD -> master, origin/master, origin/HEAD) Author: Stefan Sauer <ensonic@users.sf.net> Date: Mon Jan 8 20:43:33 2018 +0100 mkdb: ensure that fallback stability is a trimmed string The docs are not very preceise what value is supported and while we canoni- calize a few values, we must ensure the other values are atleast strings. Fixes #791928
(In reply to Stefan Sauer (gstreamer, gtkdoc dev) from comment #5) > Hmm, the code only allows {Stable|Unstable|Private} > https://git.gnome.org/browse/gtk-doc/tree/gtkdoc/mkdb.py#n2062 > Anyway, this should fix it. Thank you.