Documentation updates

MetadataExtractor/Directory.cs

@@ -47,7 +47,7 @@ protected Directory(Dictionary<int, string>? tagNameMap)
         /// <summary>Attempts to find the name of the specified tag.</summary>
         /// <param name="tagType">The tag to look up.</param>
         /// <param name="tagName">The found name, if any.</param>
-        /// <returns><c>true</c> if the tag is known and <paramref name="tagName"/> was set, otherwise <c>false</c>.</returns>
+        /// <returns><see langword="true"/> if the tag is known and <paramref name="tagName"/> was set, otherwise <see langword="false"/>.</returns>
         protected virtual bool TryGetTagName(int tagType, [NotNullWhen(returnValue: true)] out string? tagName)
         {
             if (_tagNameMap is null)
@@ -90,7 +90,7 @@ protected void SetDescriptor(ITagDescriptor descriptor)
 
         /// <summary>Gets a value indicating whether this directory has one or more errors.</summary>
         /// <remarks>Error messages are accessible via <see cref="Errors"/>.</remarks>
-        /// <returns><c>true</c> if the directory contains errors, otherwise <c>false</c></returns>
+        /// <returns><see langword="true"/> if the directory contains errors, otherwise <see langword="false"/></returns>
         public bool HasError => _errorList.Count > 0;
 
         /// <summary>Used to iterate over any error messages contained in this directory.</summary>

MetadataExtractor/DirectoryExtensions.cs

@@ -671,7 +671,7 @@ public static DateTime GetDateTime(this Directory directory, int tagType /*, Tim
         /// otherwise it will be <see cref="DateTimeKind.Unspecified"/>.
         /// </para>
         /// </remarks>
-        /// <returns><c>true</c> if a DateTime was returned, otherwise <c>false</c>.</returns>
+        /// <returns><see langword="true"/> if a DateTime was returned, otherwise <see langword="false"/>.</returns>
         [Pure]
         public static bool TryGetDateTime(this Directory directory, int tagType /*, TimeZoneInfo? timeZone = null*/, out DateTime dateTime)
         {

MetadataExtractor/Formats/Bmp/BmpHeaderDirectory.cs

@@ -69,76 +69,76 @@ public BmpHeaderDirectory() : base(_tagNameMap)
         /// </summary>
         public enum BitmapType : int
         {
-            /** "BM" - Windows or OS/2 bitmap */
+            /// <summary>"BM" - Windows or OS/2 bitmap</summary>
             Bitmap = 0x4D42,
 
-            /** "BA" - OS/2 Bitmap array (multiple bitmaps) */
+            /// <summary>"BA" - OS/2 Bitmap array (multiple bitmaps)</summary>
             OS2BitmapArray = 0x4142,
 
-            /** "IC" - OS/2 Icon */
+            /// <summary>"IC" - OS/2 Icon</summary>
             OS2Icon = 0x4349,
 
-            /** "CI" - OS/2 Color icon */
+            /// <summary>"CI" - OS/2 Color icon</summary>
             OS2ColorIcon = 0x4943,
 
-            /** "CP" - OS/2 Color pointer */
+            /// <summary>"CP" - OS/2 Color pointer</summary>
             OS2ColorPointer = 0x5043,
 
-            /** "PT" - OS/2 Pointer */
+            /// <summary>"PT" - OS/2 Pointer</summary>
             OS2Pointer = 0x5450
         }
 
         public enum Compression : int
         {
-            /** 0 = None */
+            /// <summary>0 = None</summary>
             Rgb = 0,
 
-            /** 1 = RLE 8-bit/pixel */
+            /// <summary>1 = RLE 8-bit/pixel</summary>
             Rle8 = 1,
 
-            /** 2 = RLE 4-bit/pixel */
+            /// <summary>2 = RLE 4-bit/pixel</summary>
             Rle4 = 2,
 
-            /** 3 = Bit fields (not OS22XBITMAPHEADER (size 64)) */
+            /// <summary>3 = Bit fields (not OS22XBITMAPHEADER (size 64))</summary>
             BitFields = 3,
 
-            /** 3 = Huffman 1D (if OS22XBITMAPHEADER (size 64)) */
+            /// <summary>3 = Huffman 1D (if OS22XBITMAPHEADER (size 64))</summary>
             Huffman1D = 3,
 
-            /** 4 = JPEG (not OS22XBITMAPHEADER (size 64)) */
+            /// <summary>4 = JPEG (not OS22XBITMAPHEADER (size 64))</summary>
             Jpeg = 4,
 
-            /** 4 = RLE 24-bit/pixel (if OS22XBITMAPHEADER (size 64)) */
+            /// <summary>4 = RLE 24-bit/pixel (if OS22XBITMAPHEADER (size 64))</summary>
             Rle24 = 4,
 
-            /** 5 = PNG */
+            /// <summary>5 = PNG</summary>
             Png = 5,
 
-            /** 6 = RGBA bit fields */
+            /// <summary>6 = RGBA bit fields</summary>
             AlphaBitFields = 6,
 
-            /** 11 = CMYK */
+            /// <summary>11 = CMYK</summary>
             Cmyk = 11,
 
-            /** 12 = CMYK RLE-8 */
+            /// <summary>12 = CMYK RLE-8</summary>
             CmykRle8 = 12,
 
-            /** 13 = CMYK RLE-4 */
+            /// <summary>13 = CMYK RLE-4</summary>
             CmykRle4 = 13
         }
 
         public enum RenderingHalftoningAlgorithm : int
         {
-            /** No halftoning algorithm */
+            /// <summary>No halftoning algorithm</summary>
             None = 0,
 
-            /** Error Diffusion Halftoning */
+            /// <summary>Error Diffusion Halftoning</summary>
             ErrorDiffusion = 1,
 
-            /** Processing Algorithm for Noncoded Document Acquisition */
+            /// <summary>Processing Algorithm for Noncoded Document Acquisition</summary>
             Panda = 2,
 
-            /** Super-circle Halftoning */
+            /// <summary>Super-circle Halftoning</summary>
             SuperCircle = 3
         }
 
@@ -149,34 +149,34 @@ public enum ColorEncoding : int
 
         public enum ColorSpaceType : long
         {
-            /** 0 = Calibrated RGB */
+            /// <summary>0 = Calibrated RGB</summary>
             LcsCalibratedRgb = 0L,
 
-            /** "sRGB" = sRGB Color Space */
+            /// <summary>"sRGB" = sRGB Color Space</summary>
             LcsSRgb = 0x73524742L,
 
-            /** "Win " = System Default Color Space, sRGB */
+            /// <summary>"Win " = System Default Color Space, sRGB</summary>
             LcsWindowsColorSpace = 0x57696E20L,
 
-            /** "LINK" = Linked Profile */
+            /// <summary>"LINK" = Linked Profile</summary>
             ProfileLinked = 0x4C494E4BL,
 
-            /** "MBED" = Embedded Profile */
+            /// <summary>"MBED" = Embedded Profile</summary>
             ProfileEmbedded = 0x4D424544L
         }
 
         public enum RenderingIntent : long
         {
-            /** Graphic, Saturation */
+            /// <summary>Graphic, Saturation</summary>
             LcsGmBusiness = 1,
 
-            /** Proof, Relative Colorimetric */
+            /// <summary>Proof, Relative Colorimetric</summary>
             LcsGmGraphics = 2,
 
-            /** Picture, Perceptual */
+            /// <summary>Picture, Perceptual</summary>
             LcsGmImages = 4,
 
-            /** Match, Absolute Colorimetric */
+            /// <summary>Match, Absolute Colorimetric</summary>
             LcsGmAbsColorimetric = 8
         }
     }

MetadataExtractor/Formats/Eps/EpsReader.cs

@@ -280,25 +280,6 @@ private static byte[] ReadUntil(SequentialReader reader, ReadOnlySpan<byte> sent
             return bytes.ToArray();
         }
 
-        /**
-         * EPS files can contain hexadecimal-encoded ASCII blocks, each prefixed with <c>"% "</c>.
-         * This method reads such a block and returns a byte[] of the decoded contents.
-         * Reading stops at the first invalid line, which is discarded (it's a terminator anyway).
-         * <p/>
-         * For example:
-         * <pre><code>
-         * %BeginPhotoshop: 9564
-         * % 3842494D040400000000005D1C015A00031B25471C0200000200041C02780004
-         * % 6E756C6C1C027A00046E756C6C1C025000046E756C6C1C023700083230313630
-         * % 3331311C023C000B3131343335362B303030301C023E00083230313630333131
-         * % 48000000010000003842494D03FD0000000000080101000000000000
-         * %EndPhotoshop
-         * </code></pre>
-         * When calling this method, the reader must be positioned at the start of the first line containing
-         * hex data, not at the introductory line.
-         *
-         * @return The decoded bytes, or <code>null</code> if decoding failed.
-         */
         /// <remarks>
         /// EPS files can contain hexadecimal-encoded ASCII blocks, each prefixed with "% ".
         /// This method reads such a block and returns a byte[] of the decoded contents.
@@ -316,7 +297,7 @@ private static byte[] ReadUntil(SequentialReader reader, ReadOnlySpan<byte> sent
         /// When calling this method, the reader must be positioned at the start of the first line containing
         /// hex data, not at the introductory line.
         /// </remarks>
-        /// <returns>The decoded bytes, or null if decoding failed.</returns>
+        /// <returns>The decoded bytes, or <see langword="null"/> if decoding failed.</returns>
         private static byte[]? DecodeHexCommentBlock(SequentialReader reader)
         {
             var bytes = new MemoryStream();

MetadataExtractor/Formats/Exif/makernotes/PanasonicMakernoteDirectory.cs

@@ -599,7 +599,7 @@ private static IEnumerable<Face> ParseFaces(byte[]? bytes, int firstRecordOffset
 
         /// <summary>Attempts to convert the underlying string value (as stored in the directory) into an Age object.</summary>
         /// <param name="tag">The tag identifier.</param>
-        /// <returns>The parsed Age object, or null if the tag was empty of the value unable to be parsed.</returns>
+        /// <returns>The parsed Age object, or <see langword="null"/> if the tag was empty of the value unable to be parsed.</returns>
         public Age? GetAge(int tag)
         {
             var ageString = this.GetString(tag);

MetadataExtractor/Formats/Iptc/Iso2022Converter.cs

@@ -43,7 +43,7 @@ public static class Iso2022Converter
         /// The two other checks are less reliable.
         /// </remarks>
         /// <param name="bytes">some text as bytes</param>
-        /// <returns>the name of the encoding or null if none could be guessed</returns>
+        /// <returns>the name of the encoding or <see langword="null"/> if none could be guessed</returns>
         internal static Encoding? GuessEncoding(byte[] bytes)
         {
             // First, give ASCII a shot

MetadataExtractor/Formats/Riff/IRiffHandler.cs

@@ -10,33 +10,33 @@ namespace MetadataExtractor.Formats.Riff
     public interface IRiffHandler
     {
         /// <summary>Gets whether the specified RIFF identifier is of interest to this handler.</summary>
-        /// <remarks>Returning <c>false</c> causes processing to stop after reading only the first twelve bytes of data.</remarks>
+        /// <remarks>Returning <see langword="false"/> causes processing to stop after reading only the first twelve bytes of data.</remarks>
         /// <param name="identifier">The four character code identifying the type of RIFF data</param>
         /// <returns>true if processing should continue, otherwise false</returns>
         bool ShouldAcceptRiffIdentifier(ReadOnlySpan<byte> identifier);
 
         /// <summary>Gets whether this handler is interested in the specific chunk type.</summary>
         /// <remarks>
-        /// Returns <c>true</c> if the data should be copied into an array and passed
-        /// to <see cref="ProcessChunk(string, byte[])"/>, or <c>false</c> to avoid
+        /// Returns <see langword="true"/> if the data should be copied into an array and passed
+        /// to <see cref="ProcessChunk(string, byte[])"/>, or <see langword="false"/> to avoid
         /// the copy and skip to the next chunk in the file, if any.
         /// </remarks>
         /// <param name="fourCc">the four character code of this chunk</param>
-        /// <returns><c>true</c> if <see cref="ProcessChunk(string, byte[])"/> should be called, otherwise <c>false</c>.</returns>
+        /// <returns><see langword="true"/> if <see cref="ProcessChunk(string, byte[])"/> should be called, otherwise <see langword="false"/>.</returns>
         bool ShouldAcceptChunk(string fourCc);
 
         /// <summary>Gets whether this handler is interested in the specific list type.</summary>
         /// <remarks>
-        /// Returns <c>true</c> if the data should be copied into an array and passed
-        /// to <see cref="ProcessChunk(string, byte[])"/>, or <c>false</c> to avoid
+        /// Returns <see langword="true"/> if the data should be copied into an array and passed
+        /// to <see cref="ProcessChunk(string, byte[])"/>, or <see langword="false"/> to avoid
         /// the copy and skip to the next chunk in the file, if any.
         /// </remarks>
         /// <param name="fourCc">the four character code of this chunk</param>
-        /// <returns><c>true</c> if <see cref="ProcessChunk(string, byte[])"/> should be called, otherwise <c>false</c>.</returns>
+        /// <returns><see langword="true"/> if <see cref="ProcessChunk(string, byte[])"/> should be called, otherwise <see langword="false"/>.</returns>
         bool ShouldAcceptList(string fourCc);
 
         /// <summary>Perform whatever processing is necessary for the type of chunk with its payload.</summary>
-        /// <remarks>This is only called if a previous call to <see cref="ShouldAcceptChunk(string)"/> with the same <c>fourCC</c> returned <c>true</c>.</remarks>
+        /// <remarks>This is only called if a previous call to <see cref="ShouldAcceptChunk(string)"/> with the same <c>fourCC</c> returned <see langword="true"/>.</remarks>
         /// <param name="fourCc">the four character code of the chunk</param>
         /// <param name="payload">they payload of the chunk as a byte array</param>
         void ProcessChunk(string fourCc, byte[] payload);

MetadataExtractor/IO/IndexedReader.cs

@@ -22,8 +22,8 @@ public abstract class IndexedReader(bool isMotorolaByteOrder)
         /// <summary>Get the byte order of this reader.</summary>
         /// <remarks>
         /// <list type="bullet">
-        ///   <item><c>true</c> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</item>
-        ///   <item><c>false</c> for Intel (or little) endianness, with LSB before MSB.</item>
+        ///   <item><see langword="true"/> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</item>
+        ///   <item><see langword="false"/> for Intel (or little) endianness, with LSB before MSB.</item>
         /// </list>
         /// </remarks>
         public bool IsMotorolaByteOrder { get; } = isMotorolaByteOrder;
@@ -35,6 +35,7 @@ public abstract class IndexedReader(bool isMotorolaByteOrder)
         public abstract int ToUnshiftedOffset(int localOffset);
 
         /// <summary>Returns the required number of bytes from the specified index from the underlying source.</summary>
+        /// <remarks>Byte ordering is not governed by <see cref="IsMotorolaByteOrder"/>.</remarks>
         /// <param name="index">The index from which the bytes begins in the underlying source</param>
         /// <param name="count">The number of bytes to be returned</param>
         /// <returns>The requested bytes</returns>
@@ -55,6 +56,9 @@ public byte[] GetBytes(int index, int count)
         /// <summary>
         /// Copies bytes from the underlying source into <paramref name="bytes"/>.
         /// </summary>
+        /// <remarks>
+        /// Byte ordering is not governed by <see cref="IsMotorolaByteOrder"/>.
+        /// </remarks>
         /// <param name="index">The index from which the bytes begins in the underlying source</param>
         /// <param name="bytes">A span of bytes to copy to. The length of this span determines how many bytes will be copied.</param>
         public abstract void GetBytes(int index, Span<byte> bytes);

MetadataExtractor/IO/SequentialReader.cs

@@ -17,26 +17,34 @@ namespace MetadataExtractor.IO
     /// <author>Drew Noakes https://drewnoakes.com</author>
     public abstract class SequentialReader(bool isMotorolaByteOrder)
     {
-        /// <summary>Get and set the byte order of this reader. <c>true</c> by default.</summary>
+        /// <summary>Get and set the byte order of this reader. <see langword="true"/> by default.</summary>
         /// <remarks>
         /// <list type="bullet">
-        ///   <item><c>true</c> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</item>
-        ///   <item><c>false</c> for Intel (or little) endianness, with LSB before MSB.</item>
+        ///   <item><see langword="true"/> for Motorola (or big) endianness (also known as network byte order), with MSB before LSB.</item>
+        ///   <item><see langword="false"/> for Intel (or little) endianness, with LSB before MSB.</item>
         /// </list>
         /// </remarks>
-        /// <value><c>true</c> for Motorola/big endian, <c>false</c> for Intel/little endian</value>
+        /// <value><see langword="true"/> for Motorola/big endian, <see langword="false"/> for Intel/little endian</value>
         public bool IsMotorolaByteOrder { get; } = isMotorolaByteOrder;
 
+        /// <summary>
+        /// Gets the current position in the sequence.
+        /// </summary>
         public abstract long Position { get; }
 
         public abstract SequentialReader WithByteOrder(bool isMotorolaByteOrder);
 
         /// <summary>Returns the required number of bytes from the sequence.</summary>
+        /// <remarks>Byte ordering is not governed by <see cref="IsMotorolaByteOrder"/>.</remarks>
         /// <param name="count">The number of bytes to be returned</param>
         /// <returns>The requested bytes</returns>
         /// <exception cref="IOException"/>
         public abstract byte[] GetBytes(int count);
 
+        /// <summary>
+        /// Populates the specified byte span with the next bytes from the sequence.
+        /// </summary>
+        /// <param name="bytes">The span of bytes to populate.</param>
         public abstract void GetBytes(Span<byte> bytes);
 
         /// <summary>Retrieves bytes, writing them into a caller-provided buffer.</summary>

MetadataExtractor/KeyValuePair.cs

@@ -3,7 +3,7 @@
 namespace MetadataExtractor
 {
     /// <summary>
-    /// Models a key/value pair, where both are non-null <see cref="string"/> objects.
+    /// Models a key/value pair, where both are non-<see langword="null"/> <see cref="string"/> objects.
     /// </summary>
     /// <author>Drew Noakes https://drewnoakes.com</author>
     public readonly struct KeyValuePair(string key, StringValue value)

MetadataExtractor/Rational.cs

@@ -104,7 +104,7 @@ public Rational(long numerator, long denominator)
         /// <remarks>May incur truncation.</remarks>
         public decimal ToDecimal() => Denominator == 0 ? 0M : Numerator / (decimal)Denominator;
 
-        /// <summary>Returns <c>true</c> if the value is non-zero, otherwise <c>false</c>.</summary>
+        /// <summary>Returns <see langword="true"/> if the value is non-zero, otherwise <see langword="false"/>.</summary>
         public bool ToBoolean() => Numerator != 0 && Denominator != 0;
 
         #region IConvertible

MetadataExtractor/Tag.cs

@@ -34,8 +34,8 @@ public Tag(int type, Directory directory)
 
         /// <summary>Get whether this tag has a name.</summary>
         /// <remarks>
-        /// If <c>true</c>, it may be accessed via <see cref="Name"/>.
-        /// If <c>false</c>, <see cref="Name"/> will return a string resembling <c>"Unknown tag (0x1234)"</c>.
+        /// If <see langword="true"/>, it may be accessed via <see cref="Name"/>.
+        /// If <see langword="false"/>, <see cref="Name"/> will return a string resembling <c>"Unknown tag (0x1234)"</c>.
         /// </remarks>
         public bool HasName => _directory.HasTagName(Type);
 

MetadataExtractor/TagDescriptor.cs

@@ -59,7 +59,7 @@ public TagDescriptor(T directory)
         /// </remarks>
         /// <param name="components">the four version values</param>
         /// <param name="majorDigits">the number of components to be</param>
-        /// <returns>the version as a string of form "2.10" or null if the argument cannot be converted</returns>
+        /// <returns>the version as a string of form "2.10" or <see langword="null"/> if the argument cannot be converted</returns>
         [Pure]
         public static string? ConvertBytesToVersionString(int[]? components, int majorDigits)
         {