Add cross-links to the PyQt4 docs, document Song, NetworkAccessManager, PlaylistSequence

doc/python/generate_python_docs.py

@@ -46,7 +46,8 @@ epydoc.docintrospecter.register_introspecter(is_pyqt_wrapper_class, introspect_p
 
 
 # Monkey-patch some functions in the HTML docwriter to show a table of contents
-# down the side of each page, instead of in a separate frame.
+# down the side of each page, instead of in a separate frame, and to do external
+# API links.
 original_write_header = epydoc.docwriter.html.HTMLWriter.write_header
 def my_write_header(self, out, title):
   original_write_header(self, out, title)
@@ -89,10 +90,57 @@ def my_write_toc_section(self, out, name, docs, fullname=True):
   docs = [x for x in docs if not str(x.canonical_name).startswith('PyQt4')]
   original_write_toc_section(self, out, name, docs, fullname=fullname)
 
+def qt_url(name):
+  if not isinstance(name, str) and \
+     not isinstance(name, epydoc.apidoc.DottedName) and \
+     not isinstance(name, unicode):
+    return None
+
+  parts = str(name).split('.')
+  if len(parts) >= 3 and parts[0] == "PyQt4":
+    parts = parts[2:]
+
+  if not parts or not parts[0].startswith("Q"):
+    return None
+
+  label = '.'.join(parts)
+  url = "http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/"
+  url += "%s.html" % parts[0].lower()
+
+  if len(parts) >= 2:
+    url += "#%s" % parts[1].lower()
+
+  return url
+
+original_translate_identifier_xref = epydoc.docwriter.html._HTMLDocstringLinker.translate_identifier_xref
+def my_translate_identifier_xref(self, identifier, label=None):
+  url = qt_url(identifier)
+  if url:
+    label = '.'.join(identifier.split('.')[2:])
+    return '<a href="%s" class="link">%s</a>' % (url, label)
+  return original_translate_identifier_xref(self, identifier, label)
+
+original_url = epydoc.docwriter.html.HTMLWriter.url
+def my_url(self, obj):
+  if isinstance(obj, epydoc.apidoc.ValueDoc):
+    url = qt_url(obj.canonical_name)
+    if url:
+      return url
+  return original_url(self, obj)
+
+original__write = epydoc.docwriter.html.HTMLWriter._write
+def my__write(self, write_func, directory, filename, *args):
+  if filename.startswith("http://"):
+    return
+  original__write(self, write_func, directory, filename, *args)
+
+epydoc.docwriter.html.HTMLWriter._write = my__write
 epydoc.docwriter.html.HTMLWriter.write_header = my_write_header
 epydoc.docwriter.html.HTMLWriter.write_footer = my_write_footer
 epydoc.docwriter.html.HTMLWriter.write_navbar = my_write_navbar
 epydoc.docwriter.html.HTMLWriter.write_toc_section = my_write_toc_section
+epydoc.docwriter.html._HTMLDocstringLinker.translate_identifier_xref = my_translate_identifier_xref
+epydoc.docwriter.html.HTMLWriter.url = my_url
 
 
 sys.argv = [
@@ -114,6 +162,10 @@ print "Running '%s'" % ' '.join(sys.argv)
 # Parse arguments
 (options, names) = epydoc.cli.parse_arguments()
 
+# Set up the logger
+logger = epydoc.cli.ConsoleLogger(1, 'hide')
+epydoc.log.register_logger(logger)
+
 # Write the main docs - this is copied from cli()
 epydoc.docstringparser.DEFAULT_DOCFORMAT = options.docformat
 docindex = epydoc.docbuilder.build_doc_index(names,

src/core/song.cpp

@@ -202,14 +202,14 @@ Song::Song(FileRefFactory* factory)
 }
 
 void Song::Init(const QString& title, const QString& artist,
-                const QString& album, qint64 length) {
+                const QString& album, qint64 length_nanosec) {
   d->valid_ = true;
 
   d->title_ = title;
   d->artist_ = artist;
   d->album_ = album;
 
-  set_length_nanosec(length);
+  set_length_nanosec(length_nanosec);
 }
 
 void Song::Init(const QString& title, const QString& artist,
@@ -224,7 +224,7 @@ void Song::Init(const QString& title, const QString& artist,
   d->end_ = end;
 }
 
-void Song::set_genre(int id) {
+void Song::set_genre_id3(int id) {
   set_genre(TStringToQString(TagLib::ID3v1::genre(id)));
 }
 

src/core/song.h

@@ -124,7 +124,7 @@ class Song {
   bool HasProperMediaFile() const;
 
   // Constructors
-  void Init(const QString& title, const QString& artist, const QString& album, qint64 length);
+  void Init(const QString& title, const QString& artist, const QString& album, qint64 length_nanosec);
   void Init(const QString& title, const QString& artist, const QString& album, qint64 beginning, qint64 end);
   void InitFromFile(const QString& filename, int directory_id);
   void InitFromQuery(const SqlRow& query, int col = 0);
@@ -246,7 +246,7 @@ class Song {
   void set_bpm(float v) { d->bpm_ = v; }
   void set_year(int v) { d->year_ = v; }
   void set_genre(const QString& v) { d->genre_ = v; }
-  void set_genre(int id);
+  void set_genre_id3(int id);
   void set_comment(const QString& v) { d->comment_ = v; }
   void set_compilation(bool v) { d->compilation_ = v; }
   void set_sampler(bool v) { d->sampler_ = v; }

src/radio/jamendoservice.cpp

@@ -340,7 +340,7 @@ Song JamendoService::ReadTrack(const QString& artist,
         int genre_id = reader->readElementText().toInt();
         // In theory, genre 0 is "blues"; in practice it's invalid.
         if (genre_id != 0) {
-          song.set_genre(genre_id);
+          song.set_genre_id3(genre_id);
         }
       } else if (name == "id") {
         QString id_text = reader->readElementText();

src/scripting/python/network.sip

@@ -4,6 +4,17 @@ class NetworkAccessManager : QNetworkAccessManager {
 #include "core/network.h"
 %End
 
+%Docstring
+A Qt network access manager that should be used to create all network requests
+in Clementine.
+
+Differences from the normal QNetworkAccessManager:
+
+  - Sends a Clementine C{User-Agent} HTTP header.
+  - Uses a thread-safe disk cache in Clementine's user config directory.
+  - Honors the proxy set by the user in the settings dialog.
+%End
+
 public:
   NetworkAccessManager(QObject* parent /TransferThis/ = 0);
 };

src/scripting/python/playlistitem.sip

@@ -30,7 +30,7 @@ L{Playlist.InsertSongsOrLibraryItems()}.
 You can get individual PlaylistItems from a L{Playlist} using
 L{Playlist.item_at()}.  Get the PlaylistItem that is currently playing (in any
 playlist) using L{Player.GetCurrentItem()}.  These functions are marked as
-returning L{PlaylistItemPtr}s, because in C++ the playlist items are held
+returning C{PlaylistItemPtr}s, because in C++ the playlist items are held
 inside and managed by smart pointers.  This doesn't affect Python at all
 however - you can use a PlaylistItemPtr in just the same way as you would a
 PlaylistItem.

src/scripting/python/playlistmanager.sip

@@ -220,7 +220,7 @@ last playlist - this function will silently return if you try.
 ChangePlaylistOrder(new_order)
 Rearranges the order of the tabs in the tab bar.
 
-@field new_order: A list of playlist IDs in the new desired order.
+@param new_order: A list of playlist IDs in the new desired order.
 @type new_order: list of ints
 %End
 

src/scripting/python/playlistsequence.sip

@@ -5,6 +5,30 @@ struct PlaylistSequence {
 #include "playlist/playlistsequence.h"
 %End
 
+%Docstring
+Contains the shuffle and repeat state of the player.
+
+This state is shared between all playlists.  You can access the global
+PlaylistSequence instance through the L{PlaylistManager}:
+
+  >>> sequence = clementine.playlists.sequence()
+  ... sequence.SetShuffleMode(clementine.PlaylistSequence.Shuffle_All)
+  ... sequence.SetRepeatMode(clementine.PlaylistSequence.Repeat_Playlist)
+
+The constants defined in this class are:
+
+  - C{Repeat_Off}
+  - C{Repeat_Track} - repeats the current track
+  - C{Repeat_Album} - repeats the current album
+  - C{Repeat_Playlist} - repeats the whole playlist
+  - C{Shuffle_Off}
+  - C{Shuffle_All} - plays tracks in a random order
+  - C{Shuffle_Album} - plays tracks from the current album in a random order
+
+@group Signals: RepeatModeChanged, ShuffleModeChanged
+@group Slots: SetRepeatMode, SetShuffleMode, SetUsingDynamicPlaylist
+%End
+
 public:
   enum RepeatMode {
     Repeat_Off = 0,
@@ -18,22 +42,77 @@ public:
     Shuffle_Album = 2,
   };
 
-  static const char* kSettingsGroup;
-
   RepeatMode repeat_mode() const;
+%Docstring
+repeat_mode() -> int
+Returns the current repeat mode.
+
+@return: one of the C{Repeat_} constants.
+%End
+
   ShuffleMode shuffle_mode() const;
+%Docstring
+shuffle_mode() -> int
+Returns the current shuffle mode.
+
+@return: one of the C{Shuffle_} constants.
+%End
 
   QMenu* repeat_menu() const;
+%Docstring
+repeat_menu() -> L{PyQt4.QtGui.QMenu}
+Returns a menu that can be added to a button or another menu to allow the user
+to control the repeat behaviour.
+%End
+
   QMenu* shuffle_menu() const;
+%Docstring
+shuffle_menu() -> L{PyQt4.QtGui.QMenu}
+Returns a menu that can be added to a button or another menu to allow the user
+to control the shuffle behaviour.
+%End
 
 public slots:
   void SetRepeatMode(PlaylistSequence::RepeatMode mode);
+%Docstring
+SetRepeatMode(mode)
+Changes the repeat mode.
+
+@param mode: one of the C{Repeat_} constants.
+%End
+
   void SetShuffleMode(PlaylistSequence::ShuffleMode mode);
+%Docstring
+SetShuffleMode(mode)
+Changes the shuffle mode.
+
+@param mode: one of the C{Shuffle_} constants.
+%End
+
   void SetUsingDynamicPlaylist(bool dynamic);
+%Docstring
+SetUsingDynamicPlaylist(dynamic)
+When using dynamic playlists changing the shuffle and repeat modes is not
+allowed, their buttons in the interface are disabled, and the L{repeat_mode()}
+and L{shuffle_mode()} functions always return C{Repeat_Off} and C{Shuffle_Off}.
+
+@type dynamic: bool
+%End
 
 signals:
   void RepeatModeChanged(PlaylistSequence::RepeatMode mode);
+%Docstring
+RepeatModeChanged(new_mode)
+Emitted when the repeat mode is changed, either by the user or by a call to
+L{SetRepeatMode()}.
+%End
+
   void ShuffleModeChanged(PlaylistSequence::ShuffleMode mode);
+%Docstring
+ShuffleModeChanged(new_mode)
+Emitted when the shuffle mode is changed, either by the user or by a call to
+L{SetShuffleMode()}.
+%End
 
 private:
   PlaylistSequence();

src/scripting/python/scriptinterface.sip

@@ -4,6 +4,26 @@ class ScriptInterface : QObject {
 #include "scripting/scriptinterface.h"
 %End
 
+%Docstring
+Helper functions that are specific to a single script running inside Clementine.
+
+An instance of this class is created as a global variable in a script's main
+package, similar to the Python global variables C{__name__} and C{__file__}.
+You can access it through C{script}:
+
+  >>> def show_settings_dialog():
+  ...   pass
+  ...
+  ... script.SettingsDialogRequested().connect(show_settings_dialog())
+
+The signals in this object are emitted by Clementine when the user does things
+related to your script, such as clicking on the Settings... button.  You should
+connect these signals to slots in your Python code and respond to them
+appropriately.
+
+@group Signals: SettingsDialogRequested
+%End
+
 %ConvertToSubClassCode
   // Any classes that inherit from QObject must be added to this list
 
@@ -49,11 +69,13 @@ class ScriptInterface : QObject {
   }
 %End
 
-public:
-  void Abort();
-
 signals:
   void SettingsDialogRequested();
+%Docstring
+SettingsDialogRequested()
+Emitted when the user clicks the Settings... button in the Script Manager
+dialog.
+%End
 
 private:
   ScriptInterface();

src/scripting/python/song.sip

@@ -4,10 +4,94 @@ class Song {
 #include "core/song.h"
 %End
 
+%Docstring
+Contains metadata and information about a music file.
+
+Song objects are used throughout Clementine to represent music files and all the
+metadata that goes along with them.  A Song contains several groups of
+functions:
+
+  - The B{constructor} functions L{Init()} and L{InitFromFile()} that are used
+    to quickly initialise the contents of a Song, either using the values you
+    provide or by reading the tags in a file on disk.
+  - The B{getters} such as L{title()} and L{artist()} that return the data
+    stored in a Song.
+  - The B{setters} such as L{set_title()} and L{set_artist()} that let you
+    change metadata in a Song.  New metadata isn't written to the actual file
+    straight away, you have to call L{Save()} or L{BackgroundSave()} first.
+  - The B{pretty getters} such as L{PrettyTitleWithArtist()} that format the
+    Song's information in various useful ways.
+
+Integer fields in the song like L{track} and L{year} will be C{-1} if they
+don't have a value set.
+
+You can get a Song object for the currently playing track by using
+L{Player.GetCurrentItem()} and L{PlaylistItem.Metadata()}:
+
+  >>> song = clementine.player.GetCurrentItem().Metadata()
+  ... print song.title()
+
+Note that Song objects are dumb containers of information - changing the fields
+in one won't automatically change the information in Clementine's database or
+save the tags to the file.  If you want to update information in the database
+such as album art, play count, skip count, rating or whether the song is in a
+compilation, use the methods in L{LibraryBackend}.  If you want to save tags
+to a music file, use the L{Save()} or L{BackgroundSave()} methods in this class
+after modifying the relevant fields.
+
+Album art for songs in Clementine is split into three different fields -
+L{art_automatic()}, L{art_manual()} and L{image()}.  L{art_automatic()} contains
+the art that was found automatically by the library scanner, for example a jpeg
+file in the same directory as the music file.  L{art_manual()} contains the art
+that was set manually by the user - if it is present it always takes priority
+over L{art_automatic()}.  These fields contain either a string with the filename
+or URL of an image file, or one of two special values - L{kManuallyUnsetCover}
+or L{kEmbeddedCover}.  The convenience functions L{has_manually_unset_cover()}
+and L{has_embedded_cover()} check for these special values.  L{image()} is a
+special field that is only currently used by radio services that want to
+display the radio station's logo and override the other two C{art_} fields.
+
+Some songs are marked as being in a compilation.  These songs are shown in the
+special "Various Artists" section in the library.  There are three different
+ways a song can be marked as being in a compilation.  L{set_compilation()} is
+set by the library scanner when it finds two or more music files in the same
+directory with different artists.  L{set_sampler()} is set by L{InitFromFile()}
+if the C{sampler} field in the ID3v2 metadata is present.
+L{set_forced_compilation_on()} and L{set_forced_compilation_off()} are set if
+the user chooses C{Show in various artists} from the right-click menu in the
+Library.  The L{is_compilation()} function returns True if the song has been
+marked in any of these ways.
+
+@group Class methods: TextForFiletype
+@group Constructors: Init, InitFromFile
+@group Save methods: Save, BackgroundSave
+@group Simple getters: is_valid, id, title, album, artist, albumartist,
+  composer, track, disc, bpm, year, genre, comment, is_compilation, rating,
+  playcount, skipcount, lastplayed, score, cue_path, has_cue, beginning_nanosec,
+  end_nanosec, length_nanosec, bitrate, samplerate, directory_id, filename,
+  basefilename, mtime, ctime, filesize, filetype, art_automatic, art_manual,
+  has_manually_unset_cover, has_embedded_cover, image, IsEditable,
+  IsMetadataEqual
+@group Pretty getters: PrettyTitle, PrettyTitleWithArtist, PrettyLength,
+  PrettyYear, TitleWithCompilationArtist
+@group Simple setters: manually_unset_cover, set_embedded_cover, set_id,
+  set_valid, set_title, set_album, set_artist, set_albumartist, set_composer,
+  set_track, set_disc, set_bpm, set_year, set_genre, set_genre_id3,
+  set_comment, set_compilation, set_sampler, set_beginning_nanosec,
+  set_end_nanosec, set_length_nanosec, set_bitrate, set_samplerate, set_mtime,
+  set_ctime, set_filesize, set_filetype, set_art_automatic, set_art_manual,
+  set_image, set_forced_compilation_on, set_forced_compilation_off, set_rating,
+  set_playcount, set_skipcount, set_lastplayed, set_score, set_cue_path,
+  set_filename, set_basefilename, set_directory_id
+%End
+
 public:
   Song();
   Song(const Song& other);
 
+  static const QString kManuallyUnsetCover;
+  static const QString kEmbeddedCover;
+
   enum FileType {
     Type_Unknown,
     Type_Asf,
@@ -26,120 +110,567 @@ public:
   };
 
   static QString TextForFiletype(FileType type);
+%Docstring
+TextForFiletype(type) -> str
+Returns a textual description of one of the C{Type_} constants.
+
+Example:
+
+  >>> print clementine.Song.TextForFiletype(clementine.Song.Type_OggVorbis)
+  "Ogg Vorbis"
+%End
+
   QString TextForFiletype() const;
 
-  // Constructors
-  void Init(const QString& title, const QString& artist, const QString& album, int length);
-  void Init(const QString& title, const QString& artist, const QString& album, int beginning, int end);
-  void InitFromFile(const QString& filename, int directory_id);
+  void Init(const QString& title, const QString& artist, const QString& album, qint64 length_nanosec);
+%Docstring
+Init(title, artist, album, length_nanosec)
+Sets the title, artist, album and length in the Song, and also marks it as
+valid.
+%End
+
+  void Init(const QString& title, const QString& artist, const QString& album, qint64 beginning, qint64 end);
+  void InitFromFile(const QString& filename, int directory_id);
+%Docstring
+InitFromFile(filename, directory_id)
+Loads tags from a music file on disk and marks the Song as valid if it was
+successful.
+
+@param directory_id: The ID of the directory containing this Song in the
+  L{LibraryBackend}.  You can pass -1 to this function to indicate the file is
+  not in the library.
+%End
 
-  // Simple accessors
   bool is_valid() const;
+%Docstring
+is_valid() -> bool
+Flag used to indicate whether an L{InitFromFile()} call returned successfully.
+%End
+
   int id() const;
+%Docstring
+id() -> int
+Identifier for this song in the L{LibraryBackend} - C{-1} if this song is not
+from the library.
+%End
 
   QString title() const;
+%Docstring
+title() -> str
+%End
+
   QString album() const;
+%Docstring
+album() -> str
+%End
+
   QString artist() const;
+%Docstring
+artist() -> str
+%End
+
   QString albumartist() const;
+%Docstring
+albumartist() -> str
+%End
+
   QString composer() const;
+%Docstring
+composer() -> str
+%End
+
   int track() const;
+%Docstring
+track() -> int
+%End
+
   int disc() const;
+%Docstring
+disc() -> int
+%End
+
   float bpm() const;
+%Docstring
+bpm() -> float
+%End
+
   int year() const;
+%Docstring
+year() -> int
+%End
+
   const QString& genre() const;
+%Docstring
+genre() -> str
+%End
+
   const QString& comment() const;
+%Docstring
+comment() -> str
+%End
+
   bool is_compilation() const;
+%Docstring
+is_compilation() -> bool
+%End
+
   float rating() const;
+%Docstring
+rating() -> float
+The song's user-assigned rating between 0.0 and 1.0.
+%End
+
   int playcount() const;
+%Docstring
+playcount() -> int
+Number of times this song has been played by Clementine.
+%End
+
   int skipcount() const;
+%Docstring
+skipcount() -> int
+Number of times this song has been skipped by the user pressing Next.
+%End
+
   int lastplayed() const;
+%Docstring
+lastplayed() -> int
+The time (in seconds since the epoch) this song was last played by Clementine.
+
+You can convert this time to a python C{datetime} object by using
+C{datetime.datetime.fromtimestamp()}.
+%End
+
   int score() const;
+%Docstring
+score() -> int
+The automatically generated score assigned to this song based on the
+L{rating()}, L{playcount()} and L{skipcount()}.
+%End
 
   const QString& cue_path() const;
+%Docstring
+cue_path() -> str
+If this song was loaded from a cuesheet then this contains the path to the
+cuesheet.
+
+@see: L{has_cue()}, L{beginning_nanosec()}, L{end_nanosec()}
+%End
+
   bool has_cue() const;
+%Docstring
+has_cue() -> bool
+Whether this song was loaded as part of a cuesheet.
 
-  int beginning_nanosec() const;
-  int end_nanosec() const;
+@see: L{cue_path()}, L{beginning_nanosec()}, L{end_nanosec()}
+%End
 
-  int length_nanosec() const;
+  qint64 beginning_nanosec() const;
+%Docstring
+beginning_nanosec() -> long
+The index in nanoseconds into the file where this song begins.
+
+This is normally 0 except when the song is part of a cuesheet.
+
+@see: L{has_cue()}, L{end_nanosec()}
+%End
+
+  qint64 end_nanosec() const;
+%Docstring
+end_nanosec() -> long
+The index in nanoseconds into the file where this song ends.
+
+This is normally 0 except when the song is part of a cuesheet.
+
+@see: L{has_cue()}, L{beginning_nanosec()}
+%End
+
+  qint64 length_nanosec() const;
+%Docstring
+length_nanosec() -> long
+The length of the song in nanoseconds.
+%End
 
   int bitrate() const;
+%Docstring
+bitrate() -> int
+%End
+
   int samplerate() const;
+%Docstring
+samplerate() -> int
+%End
 
   int directory_id() const;
+%Docstring
+directory_id() -> int
+The ID in the L{LibraryBackend} of the directory containing this song, or -1 if
+the song is not from the library.
+%End
+
   const QString& filename() const;
+%Docstring
+filename() -> str
+The filename I{or URL} of this song.
+%End
+
   const QString& basefilename() const;
+%Docstring
+basefilename() -> str
+The filename of this song without any directory component.
+%End
+
   uint mtime() const;
+%Docstring
+mtime() -> int
+The time in seconds since the epoch that this song was modified.
+
+You can convert this time to a python C{datetime} object by using
+C{datetime.datetime.fromtimestamp()}.
+
+@see: L{ctime()}
+%End
+
   uint ctime() const;
+%Docstring
+ctime() -> int
+The time in seconds since the epoch that this song was created.
+
+You can convert this time to a python C{datetime} object by using
+C{datetime.datetime.fromtimestamp()}.
+
+@see: L{mtime()}
+%End
+
   int filesize() const;
+%Docstring
+filesize() -> int
+The size of this file in bytes.
+%End
+
   FileType filetype() const;
+%Docstring
+filetype() -> FileType
+The type of media file.
+
+@see: L{TextForFiletype}
+%End
 
   QString art_automatic() const;
+%Docstring
+art_automatic() -> str
+The filename or URL of automatically discovered album art, or one of the special
+values  L{kManuallyUnsetCover} or L{kEmbeddedCover}.
+
+@see: L{art_manual()}, L{has_manually_unset_cover()}, L{has_embedded_cover()}
+%End
+
   QString art_manual() const;
+%Docstring
+art_manual() -> str
+The filename or URL of album art set by the user, or one of the special
+values  L{kManuallyUnsetCover} or L{kEmbeddedCover}.
+
+@see: L{art_automatic()}, L{has_manually_unset_cover()}, L{has_embedded_cover()}
+%End
 
   bool has_manually_unset_cover() const;
+%Docstring
+has_manually_unset_cover() -> bool
+Returns True if the album art has been manually unset by the user.
+
+@see: L{art_manual()}, L{manually_unset_cover()}
+%End
+
   void manually_unset_cover();
+%Docstring
+manually_unset_cover()
+Marks this song as having a manually unset album cover.
+
+@see: L{art_manual()}, L{has_manually_unset_cover()}
+%End
 
   bool has_embedded_cover() const;
+%Docstring
+has_embedded_cover() -> bool
+Returns True if the album art is embedded within the file.
+
+@see: L{art_automatic()}, L{set_embedded_cover()}
+%End
+
   void set_embedded_cover();
+%Docstring
+set_embedded_cover()
+Marks this song as having album art contained within it.
+
+@see: L{art_automatic()}, L{has_embedded_cover()}
+%End
 
   QImage image() const;
+%Docstring
+image() -> L{PyQt4.QtGui.QImage}
+An album art image that overrides L{art_automatic()} and L{art_manual()}.
+%End
 
   // Pretty accessors
   QString PrettyTitle() const;
+%Docstring
+PrettyTitle() -> str
+Returns the title of this song if it is set, or else returns the filename.
+%End
+
   QString PrettyTitleWithArtist() const;
+%Docstring
+PrettyTitleWithArtist() -> str
+Returns "artist - title" if both are set, otherwise returns L{PrettyTitle()}.
+%End
+
   QString PrettyLength() const;
+%Docstring
+PrettyLength() -> str
+Returns the length of the song formatted as "(hh:)mm:ss".
+%End
+
   QString PrettyYear() const;
+%Docstring
+PrettyYear() -> str
+Returns the year if it is set, otherwise returns "".
+%End
 
   QString TitleWithCompilationArtist() const;
+%Docstring
+TitleWithCompilationArtist() -> str
+If this song is part of a compilation B{and} the artist is B{not} "Various
+Artists", returns L{PrettyTitleWithArtist()}, otherwise returns L{PrettyTitle()}.
+%End
 
   // Setters
   bool IsEditable() const;
+%Docstring
+IsEditable() -> bool
+Returns True if this song is backed by a local file that is writable and is not
+part of a cue sheet.
+%End
+
   bool Save() const;
+%Docstring
+Save() -> bool
+Saves the metadata to the file and returns True if it was successful.
+
+@warning: This method is B{blocking} and should not be called from the main
+  thread.  Use the L{BackgroundSave()} method instead which works in a
+  background thread.
+%End
+
   void BackgroundSave() const;
+%Docstring
+BackgroundSave()
+Saves the metadata to the file in a background thread and returns immediately.
+%End
 
   void set_id(int id);
+%Docstring
+set_id(id)
+%End
+
   void set_valid(bool v);
+%Docstring
+set_valid(valid)
+%End
+
   void set_title(const QString& v);
+%Docstring
+set_title(title)
+%End
+
 
   void set_album(const QString& v);
-  void set_artist(const QString& v);
-  void set_albumartist(const QString& v);
-  void set_composer(const QString& v);
-  void set_track(int v);
-  void set_disc(int v);
-  void set_bpm(float v);
-  void set_year(int v);
-  void set_genre(const QString& v);
-  void set_genre(int id);
-  void set_comment(const QString& v);
-  void set_compilation(bool v);
-  void set_sampler(bool v);
-  void set_beginning_nanosec(int v);
-  void set_end_nanosec(int v);
-  void set_length_nanosec(int v);
-  void set_bitrate(int v);
-  void set_samplerate(int v);
-  void set_mtime(int v);
-  void set_ctime(int v);
-  void set_filesize(int v);
-  void set_filetype(FileType v);
-  void set_art_automatic(const QString& v);
-  void set_art_manual(const QString& v);
-  void set_image(const QImage& i);
-  void set_forced_compilation_on(bool v);
-  void set_forced_compilation_off(bool v);
-  void set_rating(float v);
-  void set_playcount(int v);
-  void set_skipcount(int v);
-  void set_lastplayed(int v);
-  void set_score(int v);
-  void set_filename(const QString& v);
-  void set_basefilename(const QString& v);
-  void set_directory_id(int v);
-  void set_cue_path(const QString& v);
+%Docstring
+set_album(album)
+%End
+
+  void set_artist(const QString& v);
+%Docstring
+set_artist(artist)
+%End
+
+  void set_albumartist(const QString& v);
+%Docstring
+set_albumartist(albumartist)
+%End
+
+  void set_composer(const QString& v);
+%Docstring
+set_composer(composer)
+%End
+
+  void set_track(int v);
+%Docstring
+set_track(track)
+%End
+
+  void set_disc(int v);
+%Docstring
+set_disc(disc)
+%End
+
+  void set_bpm(float v);
+%Docstring
+set_bpm(bpm)
+%End
+
+  void set_year(int v);
+%Docstring
+set_year(year)
+%End
+
+  void set_genre(const QString& v);
+%Docstring
+set_genre(genre)
+%End
+
+  void set_genre_id3(int id);
+%Docstring
+set_genre_id3(id)
+Sets the genre from an ID3v1 genre ID.  See
+U{Appendix A of the ID3v1 specification<http://www.id3.org/id3v2.3.0#head-129376727ebe5309c1de1888987d070288d7c7e7>}.
+%End
+
+  void set_comment(const QString& v);
+%Docstring
+set_comment(comment)
+%End
+
+  void set_compilation(bool v);
+%Docstring
+set_compilation(compilation)
+%End
+
+  void set_sampler(bool v);
+%Docstring
+set_sampler(sampler)
+%End
+
+  void set_beginning_nanosec(qint64 v);
+%Docstring
+set_beginning_nanosec(nanosec)
+%End
+
+  void set_end_nanosec(qint64 v);
+%Docstring
+set_end_nanosec(nanosec)
+%End
+
+  void set_length_nanosec(qint64 v);
+%Docstring
+set_length_nanosec(nanosec)
+%End
+
+  void set_bitrate(int v);
+%Docstring
+set_bitrate(bitrate)
+%End
+
+  void set_samplerate(int v);
+%Docstring
+set_samplerate(samplerate)
+%End
+
+  void set_mtime(int v);
+%Docstring
+set_mtime(mtime)
+%End
+
+  void set_ctime(int v);
+%Docstring
+set_ctime(ctime)
+%End
+
+  void set_filesize(int v);
+%Docstring
+set_filesize(size)
+%End
+
+  void set_filetype(FileType v);
+%Docstring
+set_filetype(type)
+%End
+
+  void set_art_automatic(const QString& v);
+%Docstring
+set_art_automatic(art)
+%End
+
+  void set_art_manual(const QString& v);
+%Docstring
+set_art_manual(art)
+%End
+
+  void set_image(const QImage& i);
+%Docstring
+set_image(image)
+%End
+
+  void set_forced_compilation_on(bool v);
+%Docstring
+set_forced_compilation_on(compilation)
+%End
+
+  void set_forced_compilation_off(bool v);
+%Docstring
+set_forced_compilation_off(compilation)
+%End
+
+  void set_rating(float v);
+%Docstring
+set_rating(rating)
+%End
+
+  void set_playcount(int v);
+%Docstring
+set_playcount(playcount)
+%End
+
+  void set_skipcount(int v);
+%Docstring
+set_skipcount(skipcount)
+%End
+
+  void set_lastplayed(int v);
+%Docstring
+set_lastplayed(lastplayed)
+%End
+
+  void set_score(int v);
+%Docstring
+set_score(score)
+%End
+
+  void set_filename(const QString& v);
+%Docstring
+set_filename(filename)
+%End
+
+  void set_basefilename(const QString& v);
+%Docstring
+set_basefilename(basefilename)
+%End
+
+  void set_directory_id(int v);
+%Docstring
+set_directory_id(directory_id)
+%End
+
+  void set_cue_path(const QString& v);
+%Docstring
+set_cue_path(cue_path)
+%End
 
-  // Comparison functions
   bool IsMetadataEqual(const Song& other) const;
+%Docstring
+IsMetadataEqual(other) -> bool
+Compares the metadata (not including ratings, playcounts, etc) with another
+Song and returns true if they are equal.
+%End
 };
 typedef QList<Song> SongList;

src/scripting/scriptinterface.cpp

@@ -27,10 +27,6 @@ ScriptInterface::ScriptInterface(Script* script, QObject* parent)
 {
 }
 
-void ScriptInterface::Abort() {
-  abort();
-}
-
 void ScriptInterface::ShowSettingsDialog() {
   emit SettingsDialogRequested();
 }

src/scripting/scriptinterface.h

@@ -31,9 +31,6 @@ class ScriptInterface : public QObject {
 public:
   ScriptInterface(Script* script, QObject* parent = 0);
 
-  // Gdb will break here
-  void Abort();
-
 public slots:
   // Callable by C++
   void ShowSettingsDialog();