Correct the API documentation

Doxyfile.cmake

@@ -12,7 +12,6 @@ OUTPUT_DIRECTORY = doc
 CREATE_SUBDIRS = NO
 ALLOW_UNICODE_NAMES = NO
 OUTPUT_LANGUAGE = English
-OUTPUT_TEXT_DIRECTION = None
 BRIEF_MEMBER_DESC = YES
 REPEAT_BRIEF = YES
 ABBREVIATE_BRIEF = "The $name class" \
@@ -239,7 +238,6 @@ PDF_HYPERLINKS = YES
 USE_PDFLATEX = YES
 LATEX_BATCHMODE = NO
 LATEX_HIDE_INDICES = NO
-LATEX_SOURCE_CODE = NO
 LATEX_BIB_STYLE = plain
 LATEX_TIMESTAMP = NO
 LATEX_EMOJI_DIRECTORY =
@@ -252,7 +250,6 @@ COMPACT_RTF = NO
 RTF_HYPERLINKS = NO
 RTF_STYLESHEET_FILE =
 RTF_EXTENSIONS_FILE =
-RTF_SOURCE_CODE = NO
 #---------------------------------------------------------------------------
 # Configuration options related to the man page output
 #---------------------------------------------------------------------------
@@ -273,7 +270,6 @@ XML_NS_MEMB_FILE_SCOPE = NO
 #---------------------------------------------------------------------------
 GENERATE_DOCBOOK = NO
 DOCBOOK_OUTPUT = docbook
-DOCBOOK_PROGRAMLISTING = NO
 #---------------------------------------------------------------------------
 # Configuration options for the AutoGen Definitions output
 #---------------------------------------------------------------------------
@@ -309,7 +305,6 @@ EXTERNAL_PAGES = YES
 #---------------------------------------------------------------------------
 # Configuration options related to the dot tool
 #---------------------------------------------------------------------------
-CLASS_DIAGRAMS = YES
 DIA_PATH =
 HIDE_UNDOC_RELATIONS = YES
 HAVE_DOT = YES

bindings/README

@@ -2,5 +2,4 @@ There are a few other people that have done bindings externally that I have
 been made aware of. I have not personally reviewed these bindings, but I'm
 listing them here so that those who find them useful are able to find them:
 
-http://developer.kde.org/~wheeler/taglib.html#bindings
-
+https://taglib.org/#language-bindings

bindings/c/tag_c.h

@@ -164,7 +164,7 @@ TAGLIB_C_EXPORT TagLib_File *taglib_file_new_iostream(TagLib_IOStream *stream);
 TAGLIB_C_EXPORT void taglib_file_free(TagLib_File *file);
 
 /*!
- * Returns true if the file is open and readable and valid information for
+ * Returns \c true if the file is open and readable and valid information for
  * the Tag and / or AudioProperties was found.
  */
 

taglib/ape/apefile.h

@@ -48,7 +48,7 @@ namespace TagLib {
  //! An implementation of APE metadata
 
  /*!
- * This is implementation of APE metadata.
+ * this is an implementation of APE metadata.
  *
  * This supports ID3v1 and APE (v1 and v2) style comments as well as reading stream
  * properties from the file.
@@ -84,7 +84,7 @@ namespace TagLib {
  };
 
  /*!
- * Constructs an APE file from \a file. If \a readProperties is true the
+ * Constructs an APE file from \a file. If \a readProperties is \c true the
  * file's audio properties will also be read.
  *
  * \note In the current implementation, \a propertiesStyle is ignored.
@@ -93,7 +93,7 @@ namespace TagLib {
  Properties::ReadStyle propertiesStyle = Properties::Average);
 
  /*!
- * Constructs an APE file from \a stream. If \a readProperties is true the
+ * Constructs an APE file from \a stream. If \a readProperties is \c true the
  * file's audio properties will also be read.
  *
  * \note TagLib will *not* take ownership of the stream, the caller is
@@ -155,15 +155,15 @@ namespace TagLib {
  /*!
  * Returns a pointer to the ID3v1 tag of the file.
  *
- * If \a create is false (the default) this may return a null pointer
- * if there is no valid ID3v1 tag. If \a create is true it will create
+ * If \a create is \c false (the default) this may return a null pointer
+ * if there is no valid ID3v1 tag. If \a create is \c true it will create
  * an ID3v1 tag if one does not exist and returns a valid pointer.
  *
  * \note This may return a valid pointer regardless of whether or not the
  * file on disk has an ID3v1 tag. Use hasID3v1Tag() to check if the file
  * on disk actually has an ID3v1 tag.
  *
- * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
+ * \note The Tag <b>is still</b> owned by the APE::File and should not be
  * deleted by the user. It will be deleted when the file (object) is
  * destroyed.
  *
@@ -174,15 +174,15 @@ namespace TagLib {
  /*!
  * Returns a pointer to the APE tag of the file.
  *
- * If \a create is false (the default) this may return a null pointer
- * if there is no valid APE tag. If \a create is true it will create
+ * If \a create is \c false (the default) this may return a null pointer
+ * if there is no valid APE tag. If \a create is \c true it will create
  * an APE tag if one does not exist and returns a valid pointer.
  *
  * \note This may return a valid pointer regardless of whether or not the
  * file on disk has an APE tag. Use hasAPETag() to check if the file
  * on disk actually has an APE tag.
  *
- * \note The Tag <b>is still</b> owned by the MPEG::File and should not be
+ * \note The Tag <b>is still</b> owned by the APE::File and should not be
  * deleted by the user. It will be deleted when the file (object) is
  * destroyed.
  *

taglib/ape/apefooter.h

@@ -70,17 +70,17 @@ namespace TagLib {
  unsigned int version() const;
 
  /*!
- * Returns true if a header is present in the tag.
+ * Returns \c true if a header is present in the tag.
  */
  bool headerPresent() const;
 
  /*!
- * Returns true if a footer is present in the tag.
+ * Returns \c true if a footer is present in the tag.
  */
  bool footerPresent() const;
 
  /*!
- * Returns true this is actually the header.
+ * Returns \c true this is actually the header.
  */
  bool isHeader() const;
 
@@ -145,8 +145,8 @@ namespace TagLib {
  ByteVector renderFooter() const;
 
  /*!
- * Renders the header corresponding to the footer. If headerPresent is
- * set to false, it returns an empty ByteVector.
+ * Renders the header corresponding to the footer. If headerPresent() is
+ * \c false, it returns an empty ByteVector.
  */
  ByteVector renderHeader() const;
 

taglib/ape/apeitem.h

@@ -63,7 +63,7 @@ namespace TagLib {
 
  /*!
  * Constructs an item with \a key and \a value.
- * If \a binary is true a Binary item will be created, otherwise \a value will be interpreted as text
+ * If \a binary is \c true a Binary item will be created, otherwise \a value will be interpreted as text
  */
  Item(const String &key, const ByteVector &value, bool binary);
 
@@ -83,7 +83,7 @@ namespace TagLib {
  Item &operator=(const Item &item);
 
  /*!
- * Exchanges the content of this item by the content of \a item.
+ * Exchanges the content of this item with the content of \a item.
  */
  void swap(Item &item) noexcept;
 
@@ -172,7 +172,7 @@ namespace TagLib {
  void setReadOnly(bool readOnly);
 
  /*!
- * Return true if the item is read-only.
+ * Return \c true if the item is read-only.
  */
  bool isReadOnly() const;
 
@@ -189,7 +189,7 @@ namespace TagLib {
  ItemTypes type() const;
 
  /*!
- * Returns if the item has any real content.
+ * Returns \c false if the item has any real content.
  */
  bool isEmpty() const;
 

taglib/ape/apetag.h

@@ -116,6 +116,7 @@ namespace TagLib {
  *
  * The only conversion done by this export function is to rename the APE tags
  * TRACK to TRACKNUMBER, YEAR to DATE, and ALBUM ARTIST to ALBUMARTIST, respectively,
+ * (and a few other keys, see \ref p_propertymapping)
  * in order to be compliant with the names used in other formats.
  */
  PropertyMap properties() const override;
@@ -165,7 +166,7 @@ namespace TagLib {
 
  /*!
  * Adds to the text item specified by \a key the data \a value. If \a replace
- * is true, then all of the other values on the same key will be removed
+ * is \c true, then all of the other values on the same key will be removed
  * first. If a binary item exists for \a key it will be removed first.
  */
  void addValue(const String &key, const String &value, bool replace = true);
@@ -184,7 +185,7 @@ namespace TagLib {
  void setItem(const String &key, const Item &item);
 
  /*!
- * Returns true if the tag does not contain any data.
+ * Returns \c true if the tag does not contain any data.
  */
  bool isEmpty() const override;
 

taglib/asf/asfattribute.h

@@ -38,6 +38,8 @@ namespace TagLib
  class File;
  class Picture;
 
+ //! Attribute of ASF (WMA) metadata
+
  class TAGLIB_EXPORT Attribute
  {
  public:
@@ -114,7 +116,7 @@ namespace TagLib
  Attribute &operator=(const Attribute &other);
 
  /*!
- * Exchanges the content of the Attribute by the content of \a other.
+ * Exchanges the content of the Attribute with the content of \a other.
  */
  void swap(Attribute &other) noexcept;
 

taglib/asf/asffile.h

@@ -35,6 +35,8 @@
 namespace TagLib {
  //! An implementation of ASF (WMA) metadata
  namespace ASF {
+ //! An implementation of TagLib::File with ASF specific methods
+
  /*!
  * This implements and provides an interface for ASF files to the
  * TagLib::Tag and TagLib::AudioProperties interfaces by way of implementing
@@ -112,7 +114,7 @@ namespace TagLib {
  /*!
  * Save the file.
  *
- * This returns true if the save was successful.
+ * This returns \c true if the save was successful.
  */
  bool save() override;
 

taglib/asf/asfpicture.h

@@ -50,7 +50,7 @@ namespace TagLib
  class TAGLIB_EXPORT Picture {
  public:
 
- /*!
+ /*
  * This describes the function or content of the picture.
  */
  DECLARE_PICTURE_TYPE_ENUM(Type)
@@ -76,12 +76,12 @@ namespace TagLib
  Picture& operator=(const Picture& other);
 
  /*!
- * Exchanges the content of the Picture by the content of \a other.
+ * Exchanges the content of the Picture with the content of \a other.
  */
  void swap(Picture &other) noexcept;
 
  /*!
- * Returns true if Picture stores valid picture
+ * Returns \c true if Picture stores valid picture
  */
  bool isValid() const;
 
@@ -136,7 +136,7 @@ namespace TagLib
  /*!
  * Returns the image data as a ByteVector.
  *
- * \note ByteVector has a data() method that returns a const char * which
+ * \note ByteVector has a data() method that returns a <tt>const char *</tt> which
  * should make it easy to export this data to external programs.
  *
  * \see setPicture()

taglib/asf/asftag.h

@@ -39,6 +39,8 @@ namespace TagLib {
  using AttributeList = List<Attribute>;
  using AttributeListMap = Map<String, AttributeList>;
 
+ //! An implementation of ASF (WMA) tags
+
  class TAGLIB_EXPORT Tag : public TagLib::Tag {
 
  friend class File;
@@ -64,7 +66,7 @@ namespace TagLib {
 
  /*!
  * Returns the album name; if no album name is present in the tag
- * String::null will be returned.
+ * an empty string will be returned.
  */
  String album() const override;
 
@@ -74,7 +76,7 @@ namespace TagLib {
  String comment() const override;
 
  /*!
- * Returns the genre name; if no genre is present in the tag String::null
+ * Returns the genre name; if no genre is present in the tag an empty string
  * will be returned.
  */
  String genre() const override;
@@ -85,7 +87,7 @@ namespace TagLib {
  virtual String rating() const;
 
  /*!
- * Returns the genre name; if no genre is present in the tag String::null
+ * Returns the genre name; if no genre is present in the tag an empty string
  * will be returned.
  */
  virtual String copyright() const;
@@ -112,7 +114,7 @@ namespace TagLib {
  void setArtist(const String &value) override;
 
  /*!
- * Sets the album to \a value. If \a value is String::null then this value will be
+ * Sets the album to \a value. If \a value is an empty string then this value will be
  * cleared.
  */
  void setAlbum(const String &value) override;
@@ -148,7 +150,7 @@ namespace TagLib {
  void setTrack(unsigned int value) override;
 
  /*!
- * Returns true if the tag does not contain any data. This should be
+ * Returns \c true if the tag does not contain any data. This should be
  * reimplemented in subclasses that provide more than the basic tagging
  * abilities in this class.
  */
@@ -168,7 +170,7 @@ namespace TagLib {
  const AttributeListMap &attributeListMap() const;
 
  /*!
- * \return True if a value for \a key is currently set.
+ * \return \c true if a value for \a key is currently set.
  */
  bool contains(const String &key) const;