GNOME Bugzilla – Bug 314023
Meta-bug to track documentation progress of various RB's files
Last modified: 2018-05-24 10:47:06 UTC
Documentation bug Section: Everywhere Nothing Correct version: Everything Other information:
These are the undocumented files (replace .xml by .c): rb-debug.xml rb-enums.xml rb-file-helpers.xml rb-glade-helpers.xml rb-preferences.xml rb-stock-icons.xml rb-string-helpers.xml rb-tree-dnd.xml rb-util.xml rb-metadata.xml rb-player.xml rb-recorder.xml rhythmdb-property-model.xml rhythmdb-query-model.xml rhythmdb-tree.xml rhythmdb.xml rb-history.xml rb-playlist-manager.xml rb-play-order-linear-loop.xml rb-play-order-linear.xml rb-play-order-random-by-age-and-rating.xml rb-play-order-random-by-age.xml rb-play-order-random-by-rating.xml rb-play-order-random-equal-weights.xml rb-play-order-random.xml rb-play-order-shuffle.xml rb-play-order.xml rb-shell-clipboard.xml rb-shell-player.xml rb-shell-preferences.xml rb-shell.xml rb-source-header.xml rb-iradio-source.xml rb-library-source.xml rb-playlist-source-recorder.xml rb-playlist-source.xml rb-sourcelist-model.xml rb-sourcelist.xml rb-source.xml rb-cell-renderer-pixbuf.xml rb-cell-renderer-rating.xml rb-dialog.xml rb-entry-view.xml rb-header.xml rb-load-failure-dialog.xml rb-property-view.xml rb-query-creator.xml rb-rating-helper.xml rb-rating.xml rb-search-entry.xml rb-song-display-box.xml rb-song-info.xml rb-statusbar.xml rb-tray-icon.xml rb-tree-model-sort.xml Maybe some need not to be documented, please comment here.
I started documenting rb-source.[ch], since it's obvious it is needed for RB sources implementation
The playorder implementations (rb-play-order-linear* and rb-play-order-random*) probably don't need documenting. Hmm... the rb-tree-model-sort files shouldn't be there, maybe I forgot to remove them from cvs when I committed the patch to switch to the standard GTK tree model implementation (they aren't used).
I removed all these files, and added them in the header ignore list, if this is all, i think the gtk-doc can be committed ?
Created attachment 53829 [details] [review] start of rhythmdb api doc This is the start of some API docs for Rhythmdb. I'm planning to write the rest and polish it up sometime soon, but I'm putting it here so it doesn't get lost.
I committed that patch and a but more RhythmDB api doc work. It's not great, but it's a start.
As part of the play queue changes, I documented rb-play-order.c. I didn't see anything in any of the other play order files that needed documenting.
I've been working on this pretty hard lately.. gtk-doc reports 21% symbol coverage, but that includes a lot of plugin symbols that I don't plan on documenting. I'm thinking we should delete doc/reference/tmpl/* from svn, since we're not adding documentation there and they cause spurious diffs frequently.
Created attachment 135455 [details] [review] adds documentation to lib/rb-file-helpers.c Here is some documentation (gtk-doc) for rb-file-helpers.
There's no need to document static functions, like rb_find_user_file and get_uri_perm, or internal data structures, like RBUriHandleRecursivelyAsyncData. These are not visible from outside of that file, and they're not part of the API. For API documentation to be useful, it needs to convey information that isn't already apparent from the function prototype. For instance, the documentation rb_file() should describe the actual paths searched, and the documentation for rb_dot_dir() should explain that it is obsolete, and that rb_user_data_dir() or rb_user_cache_dir() should be used instead.
-- GitLab Migration Automatic Message -- This bug has been migrated to GNOME's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.gnome.org/GNOME/rhythmbox/issues/71.