From 45ab6b17b927913c940fc21e77683618e117fb98 Mon Sep 17 00:00:00 2001
From: Martchus <martchus@gmx.net>
Date: Tue, 23 Jan 2024 00:29:11 +0100
Subject: [PATCH] Improve various details of documentation

---
 README.md                 | 2 +-
 doc/example.cpp           | 8 ++++----
 vorbis/vorbiscommentids.h | 7 ++++++-
 3 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 6ee3b1d..040ddec 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ The library is aware of different text encodings and can convert between differe
 
 ### Further documentation
 For more examples check out the command line interface of [Tag Editor](https://github.com/Martchus/tageditor).
-API documentation can be generated using Doxygen with `make tagparser_apidoc`.
+API documentation can be generated using Doxygen with `cmake --build … --target tagparser_apidoc`.
 
 ## Bugs, stability
 Bugs can be reported on GitHub.
diff --git a/doc/example.cpp b/doc/example.cpp
index 56c5a33..937fd3f 100644
--- a/doc/example.cpp
+++ b/doc/example.cpp
@@ -42,12 +42,13 @@ void example()
     //   code.
     // - Parsing a file can be expensive if the file is big or the disk IO is slow. You might want to
     //   run it in a separate thread.
-    // - At this point the parser does not make much use of the progress object.
+    // - At this point the parser does not make much use of the progress object (in contrast to applyChanges()
+    //   shown below).
     fileInfo.parseContainerFormat(diag, progress);
     fileInfo.parseTags(diag, progress);
     fileInfo.parseAttachments(diag, progress);
     fileInfo.parseChapters(diag, progress);
-    fileInfo.parseEverything(diag, progress); // just use that one if you want all over the above
+    fileInfo.parseEverything(diag, progress); // just use that one if you want all of the above
 
     // get tag as an object derived from the Tag class
     // notes:
@@ -55,7 +56,7 @@ void example()
     //   fileInfo.createAppropriateTags(…) to create tags as needed.
     auto tag = fileInfo.tags().at(0);
 
-    // extract a field value and convert it to UTF-8 std::string (toString() might throw ConversionException)
+    // extract a field value and convert it to a UTF-8 std::string (toString() might throw ConversionException)
     auto title = tag->value(TagParser::KnownField::Title).toString(TagParser::TagTextEncoding::Utf8);
 
     // change a field value using an encoding suitable for the tag format
@@ -84,6 +85,5 @@ void example()
     // - Use progress.tryToAbort() from another thread or an interrupt handler to abort gracefully without leaving
     //   the file in an inconsistent state.
     // - Be sure everything has been parsed before as the library needs to be aware of the whole file structure.
-    fileInfo.parseEverything(diag, progress);
     fileInfo.applyChanges(diag, progress);
 }
diff --git a/vorbis/vorbiscommentids.h b/vorbis/vorbiscommentids.h
index 55f9d54..aa47e56 100644
--- a/vorbis/vorbiscommentids.h
+++ b/vorbis/vorbiscommentids.h
@@ -9,7 +9,12 @@ namespace TagParser {
 
 /*!
  * \brief Encapsulates Vorbis comment field names.
- * \sa See https://xiph.org/vorbis/doc/v-comment.html for the upstream documentation of the field names.
+ * \sa
+ * - See https://xiph.org/vorbis/doc/v-comment.html for the upstream documentation of the field names.
+ * - See https://wiki.xiph.org/Field_names for an additional proposal that is most notably introducing
+ *   `DISCNUMBER` and `…TOTAL` fields.
+ * - See https://wiki.hydrogenaud.io/index.php?title=Tag_Mapping for further conventions and a
+ *   comparision with other formats.
  */
 namespace VorbisCommentIds {