spotify 12.5.3 → 12.6.0

data/lib/spotify/api/album_browse.rb

@@ -1,18 +1,96 @@
 module Spotify
   class API
     # @!group AlbumBrowse
+
+    # @example
+    #   # this is called some time later, as a result of calling {#session_process_events}
+    #   browse_callback = proc do |album_browse|
+    #     puts "Album browse has completed!"
+    #   end
+    #   album_browse = Spotify.albumbrowse_create(session, album, browse_callback, nil)
+    #
+    # @note make *very* sure the callback proc is not garbage collected before it is called!
+    # @param [Session] session
+    # @param [Album] album
+    # @param [Proc<AlbumBrowse, FFI::Pointer>] callback
+    # @param [FFI::Pointer] userdata
+    # @return [AlbumBrowse] a request for browsing an album
+    # @method albumbrowse_create(session, album, albumbrowse_complete_callback, userdata)
     attach_function :albumbrowse_create, [ Session, Album, :albumbrowse_complete_cb, :userdata ], AlbumBrowse
+
+    # @param [AlbumBrowse] album_browse
+    # @return [Boolean] true if the album browse request has completed
+    # @method albumbrowse_is_loaded(album_browse)
     attach_function :albumbrowse_is_loaded, [ AlbumBrowse ], :bool
-    attach_function :albumbrowse_error, [ AlbumBrowse ], :error
+
+    # @param [AlbumBrowse] album_browse
+    # @return [Symbol] album browsing error code
+    # @method albumbrowse_error(album_browse)
+    attach_function :albumbrowse_error, [ AlbumBrowse ], APIError
+
+    # @see #albumbrowse_is_loaded
+    # @note the album browse request must have completed, or this function always return nil.
+    # @param [AlbumBrowse] album_browse
+    # @return [Album, nil] the album being browsed
+    # @method albumbrowse_album(album_browse)
     attach_function :albumbrowse_album, [ AlbumBrowse ], Album
+
+    # @see #albumbrowse_is_loaded
+    # @note the album browse request must have completed, or this function always return nil.
+    # @param [AlbumBrowse] album_browse
+    # @return [Artist, nil] the authoring artist of the album being browsed
+    # @method albumbrowse_artist(album_browse)
     attach_function :albumbrowse_artist, [ AlbumBrowse ], Artist
+
+    # @see #albumbrowse_is_loaded
+    # @see #albumbrowse_copyright
+    # @note the album browse request must have completed, or this function always return 0.
+    # @param [AlbumBrowse] album_browse
+    # @return [Integer] number of copyright strings on the album being browsed
+    # @method albumbrowse_num_copyrights(album_browse)
     attach_function :albumbrowse_num_copyrights, [ AlbumBrowse ], :int
+
+    # @see #albumbrowse_is_loaded
+    # @see #albumbrowse_num_copyrights
+    # @note if index is out of range, returns nil.
+    # @param [AlbumBrowse] album_browse
+    # @param [Integer] index number within 0...{#albumbrowse_num_copyrights}
+    # @return [String, nil] the copyright string at index
+    # @method albumbrowse_copyright(album_browse, index)
     attach_function :albumbrowse_copyright, [ AlbumBrowse, :int ], UTF8String
+
+    # @see #albumbrowse_is_loaded
+    # @see #albumbrowse_track
+    # @note the album browse request must have completed, or this function always return 0.
+    # @param [AlbumBrowse] album_browse
+    # @return [Integer] number of tracks on the album being browsed
+    # @method albumbrowse_num_tracks(album_browse)
     attach_function :albumbrowse_num_tracks, [ AlbumBrowse ], :int
+
+    # @see #albumbrowse_is_loaded
+    # @see #albumbrowse_num_tracks
+    # @note if index is out of range, returns nil.
+    # @param [AlbumBrowse] album_browse
+    # @param [Integer] index number within 0...{#albumbrowse_num_tracks}
+    # @return [Track, nil] the track at index
+    # @method albumbrowse_track(album_browse, index)
     attach_function :albumbrowse_track, [ AlbumBrowse, :int ], Track
+
+    # @see #albumbrowse_is_loaded
+    # @note the album browse request must have completed, or this function always return an empty string.
+    # @param [AlbumBrowse] album_browse
+    # @return [String] the review for the album being browsed
+    # @method albumbrowse_review(album_browse)
     attach_function :albumbrowse_review, [ AlbumBrowse ], UTF8String
+
+    # @see #albumbrowse_is_loaded
+    # @note the album browse request must have completed, or this function will return an undefined value.
+    # @param [AlbumBrowse] album_browse
+    # @return [Integer] the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache
+    # @method albumbrowse_backend_request_duration(album_browse)
     attach_function :albumbrowse_backend_request_duration, [ AlbumBrowse ], :int
-    attach_function :albumbrowse_add_ref, [ AlbumBrowse ], :error
-    attach_function :albumbrowse_release, [ AlbumBrowse ], :error
+
+    attach_function :albumbrowse_add_ref, [ AlbumBrowse ], APIError
+    attach_function :albumbrowse_release, [ AlbumBrowse ], APIError
   end
 end

data/lib/spotify/api/artist.rb

@@ -1,10 +1,29 @@
 module Spotify
   class API
     # @!group Artist
+
+    # @see #artist_is_loaded
+    # @note the artist must be loaded, or this function always return an empty string.
+    # @param [Artist] artist
+    # @return [String] name of the artist
+    # @method artist_name(artist)
     attach_function :artist_name, [ Artist ], UTF8String
+
+    # @param [Artist] artist
+    # @return [Boolean] true if the artist is populated with data
+    # @method artist_is_loaded(artist)
     attach_function :artist_is_loaded, [ Artist ], :bool
+
+    # @see #image_create
+    # @see #artist_is_loaded
+    # @note the artist must be loaded, or this function always return nil.
+    # @param [Artist] artist
+    # @param [Symbol] image_size one of :normal, :small, :large
+    # @return [String, nil] image ID to pass to {#image_create}, or nil if the artist has no image
+    # @method artist_portrait(artist, image_size)
     attach_function :artist_portrait, [ Artist, :image_size ], ImageID
-    attach_function :artist_add_ref, [ Artist ], :error
-    attach_function :artist_release, [ Artist ], :error
+
+    attach_function :artist_add_ref, [ Artist ], APIError
+    attach_function :artist_release, [ Artist ], APIError
   end
 end

data/lib/spotify/api/artist_browse.rb

@@ -1,23 +1,141 @@
 module Spotify
   class API
     # @!group ArtistBrowse
+
+    # @example
+    #   # this is called some time later, as a result of calling {#session_process_events}
+    #   browse_callback = proc do |artist_browse|
+    #     puts "Artist browse has completed!"
+    #   end
+    #   artist_browse = Spotify.artistbrowse_create(session, artist, :no_albums, browse_callback, nil)
+    #
+    # @note make *very* sure the callback proc is not garbage collected before it is called!
+    # @param [Session] session
+    # @param [Artist] artist
+    # @param [Symbol] type one of :full, :no_tracks, :no_albums
+    # @param [Proc<ArtistBrowse, FFI::Pointer>] callback
+    # @param [FFI::Pointer] userdata
+    # @return [ArtistBrowse] a request for browsing an artist
+    # @method artistbrowse_create(session, artist, type, callback, userdata)
     attach_function :artistbrowse_create, [ Session, Artist, :artistbrowse_type, :artistbrowse_complete_cb, :userdata ], ArtistBrowse
+
+    # @param [ArtistBrowse] artist_browse
+    # @return [Boolean] true if the artist browse request has completed
+    # @method artistbrowse_is_loaded(artist_browse)
     attach_function :artistbrowse_is_loaded, [ ArtistBrowse ], :bool
-    attach_function :artistbrowse_error, [ ArtistBrowse ], :error
+
+    # @param [ArtistBrowse] artist_browse
+    # @return [Symbol] artist browsing error code
+    # @method artistbrowse_error(artist_browse)
+    attach_function :artistbrowse_error, [ ArtistBrowse ], APIError
+
+    # @see #artistbrowse_is_loaded
+    # @note the artist browse request must have completed, or this function always return nil.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Artist, nil] the artist being browsed
+    # @method artistbrowse_artist(artist_browse)
     attach_function :artistbrowse_artist, [ ArtistBrowse ], Artist
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_portrait
+    # @note the artist browse request must have completed, or this function always return 0.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] number of artist portraits
+    # @method artistbrowse_num_portraits(artist_browse)
     attach_function :artistbrowse_num_portraits, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_num_portraits
+    # @note if index is out of range, returns nil.
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_portraits}
+    # @return [String, nil] image ID to pass to {#image_create}
+    # @method artistbrowse_portrait(artist_browse, index)
     attach_function :artistbrowse_portrait, [ ArtistBrowse, :int ], ImageID
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_track
+    # @note the artist browse request must have completed, or this function always return 0.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] number of artist tracks
+    # @method artistbrowse_num_tracks(artist_browse)
     attach_function :artistbrowse_num_tracks, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_num_tracks
+    # @note if index is out of range, returns nil.
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_tracks}
+    # @return [Track, nil] the track at index
+    # @method artistbrowse_track(artist_browse, index)
     attach_function :artistbrowse_track, [ ArtistBrowse, :int ], Track
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_album
+    # @note the artist browse request must have completed, or this function always return 0.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] number of artist albums
+    # @method artistbrowse_num_albums(artist_browse)
     attach_function :artistbrowse_num_albums, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_num_albums
+    # @note if index is out of range, returns nil.
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_albums}
+    # @return [Track, nil] the album at index
+    # @method artistbrowse_album(artist_browse, index)
     attach_function :artistbrowse_album, [ ArtistBrowse, :int ], Album
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_similar_artist
+    # @note the artist browse request must have completed, or this function always return 0.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] number of similar artists
+    # @method artistbrowse_num_similar_artists(artist_browse)
     attach_function :artistbrowse_num_similar_artists, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_num_similar_artists
+    # @note if index is out of range, returns nil.
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_similar_artists}
+    # @return [Track, nil] a similar artist at index
+    # @method artistbrowse_similar_artist(artist_browse, index)
     attach_function :artistbrowse_similar_artist, [ ArtistBrowse, :int ], Artist
+
+    # @see #artistbrowse_is_loaded
+    # @note the artist browse request must have completed, or this function always return an empty string.
+    # @param [ArtistBrowse] artist_browse
+    # @return [String] the review for the artist being browsed
+    # @method artistbrowse_biography(artist_browse)
     attach_function :artistbrowse_biography, [ ArtistBrowse ], UTF8String
+
+    # @see #artistbrowse_is_loaded
+    # @note the artist browse request must have completed, or this function will return an undefined value.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] the time (in ms) that was spent waiting for the Spotify backend to serve the request, -1 if served from local cache
+    # @method artistbrowse_backend_request_duration(artist_browse)
     attach_function :artistbrowse_backend_request_duration, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_tophit_track
+    # @note the artist browse request must have completed, or this function always return 0.
+    # @param [ArtistBrowse] artist_browse
+    # @return [Integer] number of tophit tracks
+    # @method artistbrowse_num_tophit_tracks(artist_browse)
     attach_function :artistbrowse_num_tophit_tracks, [ ArtistBrowse ], :int
+
+    # @see #artistbrowse_is_loaded
+    # @see #artistbrowse_num_tophit_tracks
+    # @note if index is out of range, returns nil.
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_tophit_tracks}
+    # @return [Track, nil] the tophit track at index
+    # @method artistbrowse_tophit_track(artist_browse, index)
     attach_function :artistbrowse_tophit_track, [ ArtistBrowse, :int ], Track
-    attach_function :artistbrowse_add_ref, [ ArtistBrowse ], :error
-    attach_function :artistbrowse_release, [ ArtistBrowse ], :error
+
+    attach_function :artistbrowse_add_ref, [ ArtistBrowse ], APIError
+    attach_function :artistbrowse_release, [ ArtistBrowse ], APIError
   end
 end

data/lib/spotify/api/error.rb

@@ -1,6 +1,10 @@
 module Spotify
   class API
     # @!group Error
-    attach_function :error_message, [ :error ], UTF8String
+
+    # @param [Error] error
+    # @return [String] explanatory error message for an error code
+    # @method error_message(error)
+    attach_function :error_message, [ APIError ], UTF8String
   end
 end

data/lib/spotify/api/image.rb

@@ -1,16 +1,82 @@
 module Spotify
   class API
     # @!group Image
+
+    # @param [Session] session
+    # @param [String] image_id
+    # @return [Image] image from an image id
+    # @method image_create(session, image_id)
     attach_function :image_create, [ Session, ImageID ], Image
-    attach_function :image_add_load_callback, [ Image, :image_loaded_cb, :userdata ], :error
-    attach_function :image_remove_load_callback, [ Image, :image_loaded_cb, :userdata ], :error
+
+    # Add a callback that will be invoked when the image is loaded.
+    #
+    # @note make *very* sure the callback proc is not garbage collected before it is called!
+    # @see #image_remove_load_callback
+    # @param [Image] image
+    # @param [Proc<Image, FFI::Pointer>] callback
+    # @param [FFI::Pointer] userdata
+    # @return [Symbol] error code
+    # @method image_add_load_callback(image, callback, userdata)
+    attach_function :image_add_load_callback, [ Image, :image_loaded_cb, :userdata ], APIError
+
+    # Remove an image load callback previously added with {#image_add_load_callback}.
+    #
+    # @see #image_add_load_callback
+    # @param [Image] image
+    # @param [Proc<Image, FFI::Pointer>] callback
+    # @param [FFI::Pointer] userdata
+    # @return [Symbol] error code
+    # @method image_remove_load_callback(image, callback, userdata)
+    attach_function :image_remove_load_callback, [ Image, :image_loaded_cb, :userdata ], APIError
+
+    # @note Images that don't exist in Spotify can also return true.
+    # @param [Image] image
+    # @return [Boolean] true if the image information has been retrieved
+    # @method image_is_loaded(image)
     attach_function :image_is_loaded, [ Image ], :bool
-    attach_function :image_error, [ Image ], :error
+
+    # @param [Image] image
+    # @return [Symbol] image error code
+    # @method image_error(image)
+    attach_function :image_error, [ Image ], APIError
+
+    # @see #image_is_loaded
+    # @note the image must be loaded, or this function always return :unknown.
+    # @param [Image] image
+    # @return [Symbol] image format, one of :unknown, or :jpeg
+    # @method image_format(image)
     attach_function :image_format, [ Image ], :imageformat
-    attach_function :image_data, [ Image, :buffer_out ], :pointer
+
+    # Retrieves raw image data.
+    #
+    # @example
+    #   Spotify.image_data(image) # => "\xFF\xD8\xFF\xE0…
+    #
+    # @see #image_is_loaded
+    # @note the image must be loaded, or this function always return nil.
+    # @param [Image] image
+    # @return [String, nil] raw image data, or nil if no image data available
+    # @method image_data(image)
+    attach_function :image_data, [ Image, :buffer_out ], :pointer do |image|
+      with_buffer(:size_t, clear: true) do |image_size_buffer|
+        data = sp_image_data(image, image_size_buffer)
+        image_size = image_size_buffer.read_size_t
+        data.read_bytes(image_size) if image_size > 0
+      end
+    end
+
+    # @param [Image] image
+    # @return [String] image id
+    # @method image_image_id(image)
     attach_function :image_image_id, [ Image ], ImageID
+
+    # @param [Session] session
+    # @param [Link] link
+    # @return [Image, nil] image pointed to by link, or nil if link is not a valid image link
+    # @method image_create_from_link(session, link)
     attach_function :image_create_from_link, [ Session, Link ], Image
-    attach_function :image_add_ref, [ Image ], :error
-    attach_function :image_release, [ Image ], :error
+
+    attach_function :image_add_ref, [ Image ], APIError
+    attach_function :image_release, [ Image ], APIError
   end
 end

data/lib/spotify/api/inbox.rb

@@ -1,9 +1,38 @@
 module Spotify
   class API
     # @!group Inbox
-    attach_function :inbox_post_tracks, [ Session, UTF8String, :array, :int, UTF8String, :inboxpost_complete_cb, :userdata ], Inbox
-    attach_function :inbox_error, [ Inbox ], :error
-    attach_function :inbox_add_ref, [ Inbox ], :error
-    attach_function :inbox_release, [ Inbox ], :error
+
+    # Post an array of tracks to a Spotify user's inbox.
+    #
+    # @example
+    #   callback = proc do |inbox|
+    #     puts "Message posted."
+    #   end
+    #   inbox = Spotify.inbox_post_tracks(session, "burgestrand", tracks, "You must listen to these!", callback, nil)
+    #
+    # @param [Session] session
+    # @param [String] username canonical username of recipient
+    # @param [Array<Track>, Track] tracks
+    # @param [String] message message to attach to post
+    # @param [Proc<Inbox, FFI::Pointer] callback to call on completion
+    # @param [FFI::Pointer] userdata
+    # @return [Inbox]
+    # @method inbox_post_tracks(session, username, tracks, message, callback, userdata)
+    attach_function :inbox_post_tracks, [ Session, UTF8String, :array, :int, UTF8String, :inboxpost_complete_cb, :userdata ], Inbox do |session, username, tracks, message, callback, userdata|
+      tracks = Array(tracks)
+
+      with_buffer(Spotify::Track, size: tracks.length) do |tracks_buffer|
+        tracks_buffer.write_array_of_pointer(tracks)
+        sp_inbox_post_tracks(session, username, tracks_buffer, tracks.length, message, callback, userdata)
+      end
+    end
+
+    # @param [Inbox] inbox
+    # @return [Symbol] error status of inbox post
+    # @method inbox_error(inbox)
+    attach_function :inbox_error, [ Inbox ], APIError
+
+    attach_function :inbox_add_ref, [ Inbox ], APIError
+    attach_function :inbox_release, [ Inbox ], APIError
   end
 end

data/lib/spotify/api/link.rb

@@ -1,25 +1,138 @@
 module Spotify
   class API
     # @!group Link
+
+    # Create a Link from a Spotify URI or Spotify HTTP URL.
+    #
+    # @param [String] spotify_uri can be regular spotify URI, or spotify HTTP URL
+    # @return [Link]
+    # @method link_create_from_string(spotify_uri)
     attach_function :link_create_from_string, [ BestEffortString ], Link
+
+    # @param [Track] track
+    # @param [Integer] offset number of milliseconds into track to link to
+    # @return [Link, nil]
+    # @method link_create_from_track(track, offset)
     attach_function :link_create_from_track, [ Track, :int ], Link
+
+    # @param [Album] album
+    # @return [Link, nil]
+    # @method link_create_from_album(album)
     attach_function :link_create_from_album, [ Album ], Link
+
+    # @param [Artist] artist
+    # @return [Link, nil]
+    # @method link_create_from_artist(artist)
     attach_function :link_create_from_artist, [ Artist ], Link
+
+    # @param [Search] search
+    # @return [Link, nil]
+    # @method link_create_from_search(search)
     attach_function :link_create_from_search, [ Search ], Link
+
+    # @param [Playlist] playlist
+    # @return [Link, nil]
+    # @method link_create_from_playlist(playlist)
     attach_function :link_create_from_playlist, [ Playlist ], Link
+
+    # @param [Artist] artist
+    # @param [Symbol] image_size one of :normal, :small, :large
+    # @return [Link, nil]
+    # @method link_create_from_artist_portrait(artist, image_size)
     attach_function :link_create_from_artist_portrait, [ Artist, :image_size ], Link
+
+    # @see #artistbrowse_num_portraits
+    # @param [ArtistBrowse] artist_browse
+    # @param [Integer] index number within 0...{#artistbrowse_num_portraits}
+    # @return [Link, nil]
+    # @method link_create_from_artistbrowse_portrait(artist_browse, index)
     attach_function :link_create_from_artistbrowse_portrait, [ ArtistBrowse, :int ], Link
+
+    # @param [Album] album
+    # @param [Symbol] image_size one of :normal, :small, :large
+    # @return [Link, nil]
+    # @method link_create_from_album_cover(album, image_size)
     attach_function :link_create_from_album_cover, [ Album, :image_size ], Link
+
+    # @example image id from spotify URI
+    #   image_id = ":\xD94#\xAD\xD9\x97f\xE0-V6\x05\xC6\xE7n\xD2\xB0\xE4P"
+    #   image_uri = "spotify:image:3ad93423add99766e02d563605c6e76ed2b0e450"
+    #   image = Spotify.image_create(session, image_id)
+    #   image_link = Spotify.link_create_from_image(image)
+    #
+    #   # And here are some cool equivalents:
+    #   image_id == ["3ad93423add99766e02d563605c6e76ed2b0e450"].pack("H40")
+    #   image_uri == "spotify:image:#{image_id.unpack("H40")[0]}"
+    #   image_link == Spotify.link_create_from_string(image_uri)
+    #   image == Spotify.image_create_from_link(session, image_link)
+    #
+    # @param [Image] image
+    # @return [Link]
+    # @method link_create_from_image(image)
     attach_function :link_create_from_image, [ Image ], Link
+
+    # @param [User] user
+    # @return [Link]
+    # @method link_create_from_user(user)
     attach_function :link_create_from_user, [ User ], Link
-    attach_function :link_as_string, [ Link, :buffer_out, :int ], :int
+
+    # Retrieve string representation of link.
+    #
+    # @example
+    #   Spotify.link_as_string(link) # => "spotify:user:burgestrand"
+    #
+    # @param [Link] link
+    # @return [String] string representation of the link
+    # @method link_as_string(link)
+    attach_function :link_as_string, [ Link, :buffer_out, :int ], :int do |link|
+      link_length = sp_link_as_string(link, nil, 0)
+      with_string_buffer(link_length) do |string_buffer, size|
+        sp_link_as_string(link, string_buffer, size)
+      end
+    end
+
+    # @param [Link] link
+    # @return [Symbol] type of link, one of :invalid, :track, :album, :artist, :search, :playlist, :profile, :starred, :localtrack, :image
+    # @method link_type(link)
     attach_function :link_type, [ Link ], :linktype
+
+    # @param [Link] link
+    # @return [Track, nil] track pointed to by the link, or nil if not a track
+    # @method link_as_track(link)
     attach_function :link_as_track, [ Link ], Track
-    attach_function :link_as_track_and_offset, [ Link, :buffer_out ], Track
+
+    # @example
+    #   Spotify.link_as_track_and_offset(link) # => [track, 1337]
+    #
+    # @note if the link is not a track link, this method returns nil.
+    # @note if no track offset is available in the link, the offset out will always be set to 0.
+    #
+    # @param [Link] link
+    # @return [Array<Track, Integer>, nil] track and offset (in ms) as a tuple, or nil
+    # @method link_as_track_and_offset(link)
+    attach_function :link_as_track_and_offset, [ Link, :buffer_out ], Track do |link|
+      with_buffer(:int) do |offset_buffer|
+        track = sp_link_as_track_and_offset(link, offset_buffer)
+        [track, offset_buffer.read_int] if track
+      end
+    end
+
+    # @param [Link] link
+    # @return [Album, nil] album pointed to by the link, or nil if not an album
+    # @method link_as_album(link)
     attach_function :link_as_album, [ Link ], Album
+
+    # @param [Link] link
+    # @return [Artist, nil] artist pointed to by the link, or nil if not an artist
+    # @method link_as_artist(link)
     attach_function :link_as_artist, [ Link ], Artist
+
+    # @param [Link] link
+    # @return [User, nil] user pointed to by the link, or nil if not a user
+    # @method link_as_user(link)
     attach_function :link_as_user, [ Link ], User
-    attach_function :link_add_ref, [ Link ], :error
-    attach_function :link_release, [ Link ], :error
+
+    attach_function :link_add_ref, [ Link ], APIError
+    attach_function :link_release, [ Link ], APIError
   end
 end