API docs: slightly less skeletal

Author: sampsyo

beets/library.py

@@ -1565,7 +1565,8 @@ def script(self, statements):
 
 
 class Library(object):
-    """A music library using an SQLite database as a metadata store."""
+    """A database of music containing songs and albums.
+    """
     def __init__(self, path='library.blb',
                        directory='~/Music',
                        path_formats=((PF_KEY_DEFAULT,
@@ -1703,19 +1704,17 @@ def _tx_stack(self):
             yield self._tx_stacks[thread_id]
 
     def transaction(self):
-        """Get a transaction object for interacting with the database.
-        This should *always* be used as a context manager.
+        """Get a :class:`Transaction` object for interacting directly
+        with the underlying SQLite database.
         """
         return Transaction(self)
 
 
     # Adding objects to the database.
 
     def add(self, item):
-        """Add the item as a new object to the library database. The id
-        field will be updated; the new id is returned. If copy, then
-        each item is copied to the destination location before it is
-        added.
+        """Add the :class:`Item` object to the library database. The
+        item's id field will be updated; the new id is returned.
         """
         item.added = time.time()
         if not item._lib:
@@ -1756,7 +1755,7 @@ def add(self, item):
     def add_album(self, items):
         """Create a new album in the database with metadata derived
         from its items. The items are added to the database if they
-        don't yet have an ID. Returns an Album object.
+        don't yet have an ID. Returns an :class:`Album` object.
         """
         # Set the metadata from the first item.
         album_values = dict((key, items[0][key]) for key in ALBUM_KEYS_ITEM)
@@ -1809,15 +1808,17 @@ def _fetch(self, model_cls, query, order_by=None):
         return Results(model_cls, rows, self, None if where else query)
 
     def albums(self, query=None):
-        """Get a sorted list of Album objects matching the given query.
+        """Get a sorted list of :class:`Album` objects matching the
+        given query.
         """
         order = '{0}, album'.format(
             _orelse("albumartist_sort", "albumartist")
         )
         return self._fetch(Album, query, order)
 
     def items(self, query=None):
-        """Get a sorted list of Item objects matching the given query.
+        """Get a sorted list of :class:`Item` objects matching the given
+        query.
         """
         order = '{0}, album'.format(
             _orelse("artist_sort", "artist")
@@ -1834,14 +1835,15 @@ def _get(self, model_cls, id):
         return self._fetch(model_cls, MatchQuery('id', id)).get()
 
     def get_item(self, id):
-        """Fetch an Item by its ID. Returns None if no match is found.
+        """Fetch an :class:`Item` by its ID. Returns `None` if no match is
+        found.
         """
         return self._get(Item, id)
 
     def get_album(self, item_or_id):
-        """Given an album ID or an item associated with an album,
-        return an Album object for the album. If no such album exists,
-        returns None.
+        """Given an album ID or an item associated with an album, return
+        an :class:`Album` object for the album. If no such album exists,
+        returns `None`.
         """
         if isinstance(item_or_id, int):
             album_id = item_or_id

docs/dev/api.rst

@@ -3,23 +3,77 @@ API Documentation
 
 .. currentmodule:: beets.library
 
+This page describes the internal API of beets' core. It's a work in
+progress---since beets is an application first and a library second, its API
+has been mainly undocumented until recently. Please file bugs if you run
+across incomplete or incorrect docs here.
+
+The :class:`Library` object is the central repository for data in beets. It
+represents a database containing songs, which are :class:`Item` instances, and
+groups of items, which are :class:`Album` instances.
+
 The Library Class
 -----------------
 
 .. autoclass:: Library(path, directory[, path_formats[, replacements]])
+
+    .. automethod:: items
+
+    .. automethod:: albums
+
+    .. automethod:: get_item
+
+    .. automethod:: get_album
+
+    .. automethod:: add
+
+    .. automethod:: add_album
+
+    .. automethod:: transaction
+
+Transactions
+''''''''''''
+
+The :class:`Library` class provides the basic methods necessary to access and
+manipulate its contents. To perform more complicated operations atomically, or
+to interact directly with the underlying SQLite database, you must use a
+*transaction*. For example::
+
+    lib = Library()
+    with lib.transaction() as tx:
+        items = lib.items(query)
+        lib.add_album(list(items))
+
+.. autoclass:: Transaction
     :members:
 
 Model Classes
 -------------
 
+The two model entities in beets libraries, :class:`Item` and :class:`Album`,
+share base classes that provide generic data storage. The :class:`LibModel`
+class inherits from :class:`FlexModel`, and both :class:`Item` and
+:class:`Album` inherit from it.
+
+The fields model classes can be accessed using attributes (dots, as in
+``item.artist``) or items (brackets, as in ``item['artist']``). The
+:class:`FlexModel` base class provides some methods that resemble `dict`
+objects.
+
 .. autoclass:: FlexModel
     :members:
 
 .. autoclass:: LibModel
     :members:
 
+Item
+''''
+
 .. autoclass:: Item
     :members:
 
+Album
+'''''
+
 .. autoclass:: Album
     :members: