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 314023 - Meta-bug to track documentation progress of various RB's files
Meta-bug to track documentation progress of various RB's files
Status: RESOLVED OBSOLETE
Product: rhythmbox
Classification: Other
Component: Documentation
HEAD
Other All
: Normal minor
: ---
Assigned To: RhythmBox Maintainers
RhythmBox Maintainers
Depends on:
Blocks:
 
 
Reported: 2005-08-20 11:34 UTC by Raphael Slinckx
Modified: 2018-05-24 10:47 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
start of rhythmdb api doc (10.26 KB, patch)
2005-10-24 11:44 UTC, James "Doc" Livingston
committed Details | Review
adds documentation to lib/rb-file-helpers.c (12.48 KB, patch)
2009-05-27 18:08 UTC, Thorsten Sick
needs-work Details | Review

Description Raphael Slinckx 2005-08-20 11:34:11 UTC
Documentation bug
Section: Everywhere
Nothing

Correct version:
Everything

Other information:
Comment 1 Raphael Slinckx 2005-08-20 12:00:23 UTC
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.
Comment 2 Raphael Slinckx 2005-08-20 12:03:23 UTC
I started documenting rb-source.[ch], since it's obvious it is needed for RB
sources implementation
Comment 3 James "Doc" Livingston 2005-08-20 12:26:24 UTC
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).
Comment 4 Raphael Slinckx 2005-08-20 22:55:35 UTC
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 ?
Comment 5 James "Doc" Livingston 2005-10-24 11:44:41 UTC
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.
Comment 6 James "Doc" Livingston 2005-11-15 15:20:32 UTC
I committed that patch and a but more RhythmDB api doc work. It's not great, but
it's a start.
Comment 7 Jonathan Matthew 2005-12-10 07:19:02 UTC
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.
Comment 8 Jonathan Matthew 2008-03-22 02:34:58 UTC
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.
Comment 9 Thorsten Sick 2009-05-27 18:08:30 UTC
Created attachment 135455 [details] [review]
adds documentation to lib/rb-file-helpers.c

Here is some documentation (gtk-doc) for rb-file-helpers.
Comment 10 Jonathan Matthew 2009-05-29 01:49:40 UTC
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.
Comment 11 GNOME Infrastructure Team 2018-05-24 10:47:06 UTC
-- 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.