diff --git a/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h b/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h
index 7963a6be8..05e595524 100644
--- a/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h
+++ b/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h
@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.16 $
+    Version  : $Revision: 1.17 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h,v $
 
 ------------------------------------------------------------------------------*/
@@ -124,7 +124,7 @@ using namespace boost::posix_time;
  *  </code></pre>
  *
  *  @author  $Author: fgerlits $
- *  @version $Revision: 1.16 $
+ *  @version $Revision: 1.17 $
  */
 class AudioClip : public Configurable,
                   public Playable
@@ -169,6 +169,12 @@ class AudioClip : public Configurable,
     public:
         /**
          *  Default constructor.
+         *
+         *  This constructor creates an AudioClip with a null pointer 
+         *  for all (ID, playlength, title, uri) fields!  It is meant for
+         *  internal use only.  If you want to upload a new audio clip to
+         *  the storage, use the constructor with (title, playlength, uri)
+         *  arguments.
          */
         AudioClip(void)                                    throw ()
                         : Playable(AudioClipType)
@@ -179,6 +185,11 @@ class AudioClip : public Configurable,
          *  Create an audio clip by specifying its unique ID.
          *  The other fields will be filled in by configure().
          *
+         *  This constructor creates a Playlist with a null pointer 
+         *  for all fields except the ID!  It is meant for internal use only.
+         *  If you want to upload a new audio clip to the storage, 
+         *  use the constructor with (title, playlength, uri) arguments.
+         *
          *  @param id the id of the audio clip.
          */
         AudioClip(Ptr<UniqueId>::Ref         id)           throw ()
@@ -190,7 +201,10 @@ class AudioClip : public Configurable,
         /**
          *  Create an audio clip by specifying all details, except
          *  for the title.  The title is set to the empty string.
+         *  
          *  This is used for testing purposes.
+         *  If you want to upload a new audio clip to the storage, 
+         *  use the constructor with (title, playlength, uri) arguments.
          *
          *  @param id the id of the audio clip.
          *  @param playlength the playing length of the audio clip.
@@ -204,7 +218,10 @@ class AudioClip : public Configurable,
 
         /**
          *  Create an audio clip by specifying all details.
+         *
          *  This is used for testing purposes.
+         *  If you want to upload a new audio clip to the storage, 
+         *  use the constructor with (title, playlength, uri) arguments.
          *
          *  @param id the id of the audio clip.
          *  @param playlength the playing length of the audio clip.
@@ -220,8 +237,25 @@ class AudioClip : public Configurable,
         /**
          *  Create an audio clip by specifying all details which need
          *  to be set by the user.
-         *  The ID is left blank, and can be set later using setId().
-         *  This is used when a new audio clip is uploaded to storage.
+         *  The ID is left blank (i.e., a null pointer), 
+         *  and can be set later using setId().
+         *
+         *  This constructor is used when a new audio clip is uploaded to 
+         *  the storage.  For example:
+         *  <pre><code>
+         *  Ptr<StorageClientFactory>::Ref
+         *          storageClientFactory = StorageClientFactory::getInstance();
+         *  Ptr<StorageClientInterface>::Ref
+         *          storageClient = storageClientFactory->getStorageClient();
+         *  Ptr<AudioClip>::Ref
+         *          audioClip(new AudioClip(title, playlength, uri));
+         *  storageClient->storeAudioClip(sessionId, audioClip);
+         *  std::cerr << audioClip->getId()->getId();   // has been set by the
+         *                                              //   storage client
+         *  </code></pre>
+         *
+         *  @see Storage::StorageClientFactory
+         *  @see Storage::StorageClientInterface
          *
          *  @param playlength the playing length of the audio clip.
          *  @param title      the title of the audio clip.
diff --git a/livesupport/modules/core/include/LiveSupport/Core/Playlist.h b/livesupport/modules/core/include/LiveSupport/Core/Playlist.h
index 5a7a1b39e..0cd7b1e2d 100644
--- a/livesupport/modules/core/include/LiveSupport/Core/Playlist.h
+++ b/livesupport/modules/core/include/LiveSupport/Core/Playlist.h
@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.25 $
+    Version  : $Revision: 1.26 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/Playlist.h,v $
 
 ------------------------------------------------------------------------------*/
@@ -93,7 +93,7 @@ using namespace boost::posix_time;
  *  </code></pre>
  *
  *  @author  $Author: fgerlits $
- *  @version $Revision: 1.25 $
+ *  @version $Revision: 1.26 $
  */
 class Playlist : public Configurable,
                  public Playable
@@ -183,6 +183,23 @@ class Playlist : public Configurable,
     public:
         /**
          *  Default constructor.
+         *
+         *  NOTE: this constructor creates a Playlist with a null pointer 
+         *  for both the ID and the playlength fields!  It is meant for
+         *  internal use only.
+         *
+         *  If you want to create an empty Playlist, use the storage client:
+         *  <pre><code>
+         *  Ptr<StorageClientFactory>::Ref
+         *          storageClientFactory = StorageClientFactory::getInstance();
+         *  Ptr<StorageClientInterface>::Ref
+         *          storageClient = storageClientFactory->getStorageClient();
+         *  Ptr<Playlist>::Ref
+         *          playlist = storageClient->createPlaylist(sessionId);
+         *  </code></pre>
+         *
+         *  @see Storage::StorageClientFactory
+         *  @see Storage::StorageClientInterface
          */
         Playlist(void)                          throw ()
                         : Playable(PlaylistType)
@@ -194,6 +211,8 @@ class Playlist : public Configurable,
 
         /**
          *  Create a playlist by specifying its ID only.
+         *
+         *  For internal use; see the note at the default constructor.
          */
         Playlist(Ptr<UniqueId>::Ref id)         throw ()
                         : Playable(PlaylistType)
@@ -207,7 +226,9 @@ class Playlist : public Configurable,
 
         /**
          *  Create a playlist by specifying all details, except the title.
-         *  This is used for testing purposes.
+         *
+         *  This is used for testing purposes; 
+         *  see the note at the default constructor.
          *
          *  @param id the id of the playlist.
          *  @param playlength the playing length of the playlist.
@@ -232,7 +253,9 @@ class Playlist : public Configurable,
 
         /**
          *  Create a playlist by specifying all details.
-         *  This is used for testing purposes.
+         *
+         *  This is used for testing purposes; 
+         *  see the note at the default constructor.
          *
          *  @param id the id of the playlist.
          *  @param playlength the playing length of the playlist.
@@ -410,6 +433,8 @@ class Playlist : public Configurable,
          *  If <code>it</code> is such an iterator, then <code>it->second</code>
          *  is the playlist element referenced by the iterator, and
          *  <code>it->first</code> is its relative offset in the playlist.
+         *  The playlist elements are listed in the order of their relative
+         *  offset (starting time).
          *
          *  @see begin(), end(), find()
          */