Add doc comments to JsonDocument (and friends)

* Add doc comments to all public members of JsonDocument, JsonElement, JsonProperty, and JsonValueType.
* Add "do not use this" doc comments on all internal members, because of source-package concerns.
* Change JsonElement.TokenType from internal to private because it could.

Commit migrated from https://github.com/dotnet/corefx/commit/81e9045dca63ccea9b4fe31f8ac3a035b1b1f86d

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.DbRow.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.DbRow.cs
index 78fb28d..9fe3b6d 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.DbRow.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.DbRow.cs
@@ -9,6 +9,9 @@ namespace System.Text.Json
 {
     public sealed partial class JsonDocument
     {
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be used by source-package consumers.
+        /// </summary>
         [StructLayout(LayoutKind.Sequential)]
         internal struct DbRow
         {

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs
index b0feda6..5a5ebbd 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.Parse.cs
@@ -14,6 +14,31 @@ namespace System.Text.Json
     {
         private const int UnseekableStreamInitialRentSize = 4096;
 
+        /// <summary>
+        ///   Parse memory as UTF-8-encoded text representing a single JSON value into a JsonDocument.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     The <see cref="ReadOnlyMemory{T}"/> value will be used for the entire lifetime of the
+        ///     JsonDocument object, and the caller must ensure that the data therein does not change during
+        ///     the object lifetime.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present.
+        ///   </para>
+        /// </remarks>
+        /// <param name="utf8Json">JSON text to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <returns>
+        ///   A JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="utf8Json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static JsonDocument Parse(ReadOnlyMemory<byte> utf8Json, JsonReaderOptions readerOptions = default)
         {
             CheckSupportedOptions(readerOptions);
@@ -21,6 +46,31 @@ namespace System.Text.Json
             return Parse(utf8Json, readerOptions, null);
         }
 
+        /// <summary>
+        ///   Parse a sequence as UTF-8-encoded text representing a single JSON value into a JsonDocument.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     The <see cref="ReadOnlySequence{T}"/> may be used for the entire lifetime of the
+        ///     JsonDocument object, and the caller must ensure that the data therein does not change during
+        ///     the object lifetime.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     Because the input is considered to be text, a UTF-8 Byte-Order-Mark (BOM) must not be present.
+        ///   </para>
+        /// </remarks>
+        /// <param name="utf8Json">JSON text to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <returns>
+        ///   A JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="utf8Json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static JsonDocument Parse(ReadOnlySequence<byte> utf8Json, JsonReaderOptions readerOptions = default)
         {
             CheckSupportedOptions(readerOptions);
@@ -47,6 +97,21 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   Parse a <see cref="Stream"/> as UTF-8-encoded data representing a single JSON value into a
+        ///   JsonDocument.  The Stream will be read to completion.
+        /// </summary>
+        /// <param name="utf8Json">JSON data to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <returns>
+        ///   A JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="utf8Json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static JsonDocument Parse(Stream utf8Json, JsonReaderOptions readerOptions = default)
         {
             if (utf8Json == null)
@@ -71,6 +136,22 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   Parse a <see cref="Stream"/> as UTF-8-encoded data representing a single JSON value into a
+        ///   JsonDocument.  The Stream will be read to completion.
+        /// </summary>
+        /// <param name="utf8Json">JSON data to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <param name="cancellationToken">The token to monitor for cancellation requests.</param>
+        /// <returns>
+        ///   A Task to produce a JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="utf8Json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static Task<JsonDocument> ParseAsync(
             Stream utf8Json,
             JsonReaderOptions readerOptions = default,
@@ -106,6 +187,25 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   Parse text representing a single JSON value into a JsonDocument.
+        /// </summary>
+        /// <remarks>
+        ///   The <see cref="ReadOnlyMemory{T}"/> value may be used for the entire lifetime of the
+        ///   JsonDocument object, and the caller must ensure that the data therein does not change during
+        ///   the object lifetime.
+        /// </remarks>
+        /// <param name="json">JSON text to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <returns>
+        ///   A JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static JsonDocument Parse(ReadOnlyMemory<char> json, JsonReaderOptions readerOptions = default)
         {
             CheckSupportedOptions(readerOptions);
@@ -130,6 +230,20 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   Parse text representing a single JSON value into a JsonDocument.
+        /// </summary>
+        /// <param name="json">JSON text to parse.</param>
+        /// <param name="readerOptions">Options to control the reader behavior during parsing.</param>
+        /// <returns>
+        ///   A JsonDocument representation of the JSON value.
+        /// </returns>
+        /// <exception cref="JsonReaderException">
+        ///   <paramref name="json"/> does not represent a valid single JSON value.
+        /// </exception>
+        /// <exception cref="ArgumentException">
+        ///   <paramref name="readerOptions"/> contains unsupported options.
+        /// </exception>
         public static JsonDocument Parse(string json, JsonReaderOptions readerOptions = default)
         {
             if (json == null)

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.TryGetProperty.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.TryGetProperty.cs
index 54ebb1c..8e63978 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.TryGetProperty.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.TryGetProperty.cs
@@ -9,6 +9,9 @@ namespace System.Text.Json
 {
     public sealed partial class JsonDocument
     {
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetNamedPropertyValue(int index, ReadOnlySpan<char> propertyName, out JsonElement value)
         {
             CheckNotDisposed();
@@ -109,6 +112,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetNamedPropertyValue(int index, ReadOnlySpan<byte> propertyName, out JsonElement value)
         {
             CheckNotDisposed();

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.cs
index 7c92745..ffcd37f 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonDocument.cs
@@ -10,6 +10,16 @@ using System.Runtime.CompilerServices;
 
 namespace System.Text.Json
 {
+    /// <summary>
+    ///   Provides a mechanism for examining the structural content of a JSON value without
+    ///   automatically instantiating data values.
+    /// </summary>
+    /// <remarks>
+    ///   This class utilizes resources from pooled memory to minimize the garbage collector (GC)
+    ///   impact in high-usage scenarios. Failure to properly Dispose this object will result in
+    ///   the memory not being returned to the pool, which will cause an increase in GC impact across
+    ///   various parts of the framework.
+    /// </remarks>
     public sealed partial class JsonDocument : IDisposable
     {
         private ReadOnlyMemory<byte> _utf8Json;
@@ -17,6 +27,9 @@ namespace System.Text.Json
         private byte[] _extraRentedBytes;
         private (int, string) _lastIndexAndString = (-1, null);
 
+        /// <summary>
+        ///   The <see cref="JsonElement"/> representing the value of the document.
+        /// </summary>
         public JsonElement RootElement => new JsonElement(this, 0);
 
         private JsonDocument(ReadOnlyMemory<byte> utf8Json, MetadataDb parsedData, byte[] extraRentedBytes)
@@ -28,6 +41,7 @@ namespace System.Text.Json
             _extraRentedBytes = extraRentedBytes;
         }
 
+        /// <inheritdoc />
         public void Dispose()
         {
             if (_utf8Json.IsEmpty)
@@ -49,6 +63,9 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal JsonTokenType GetJsonTokenType(int index)
         {
             CheckNotDisposed();
@@ -56,6 +73,9 @@ namespace System.Text.Json
             return _parsedData.GetJsonTokenType(index);
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal int GetArrayLength(int index)
         {
             CheckNotDisposed();
@@ -67,6 +87,9 @@ namespace System.Text.Json
             return row.SizeOrLength;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal JsonElement GetArrayIndexElement(int currentIndex, int arrayIndex)
         {
             CheckNotDisposed();
@@ -115,6 +138,9 @@ namespace System.Text.Json
             throw new IndexOutOfRangeException();
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal int GetEndIndex(int index, bool includeEndElement)
         {
             CheckNotDisposed();
@@ -193,6 +219,9 @@ namespace System.Text.Json
             return _utf8Json.Slice(start, end - start);
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetString(int index, JsonTokenType expectedType)
         {
             CheckNotDisposed();
@@ -232,12 +261,18 @@ namespace System.Text.Json
             return lastString;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetNameOfPropertyValue(int index)
         {
             // The property name is one row before the property value
             return GetString(index - DbRow.Size, JsonTokenType.PropertyName);
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out int value)
         {
             CheckNotDisposed();
@@ -260,6 +295,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out uint value)
         {
             CheckNotDisposed();
@@ -282,6 +320,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out long value)
         {
             CheckNotDisposed();
@@ -304,6 +345,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out ulong value)
         {
             CheckNotDisposed();
@@ -326,6 +370,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out double value)
         {
             CheckNotDisposed();
@@ -350,6 +397,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out float value)
         {
             CheckNotDisposed();
@@ -374,6 +424,9 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal bool TryGetValue(int index, out decimal value)
         {
             CheckNotDisposed();
@@ -398,12 +451,18 @@ namespace System.Text.Json
             return false;
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetRawValueAsString(int index)
         {
             ReadOnlyMemory<byte> segment = GetRawValue(index, includeQuotes: true);
             return JsonReaderHelper.TranscodeHelper(segment.Span);
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetPropertyRawValueAsString(int valueIndex)
         {
             ReadOnlyMemory<byte> segment = GetPropertyRawValue(valueIndex);

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ArrayEnumerator.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ArrayEnumerator.cs
index 60bfa34..06845bd 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ArrayEnumerator.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ArrayEnumerator.cs
@@ -10,12 +10,18 @@ namespace System.Text.Json
 {
     public partial struct JsonElement
     {
+        /// <summary>
+        ///   An enumerable and enumerator for the contents of a JSON array.
+        /// </summary>
         public struct ArrayEnumerator : IEnumerable<JsonElement>, IEnumerator<JsonElement>
         {
             private readonly JsonElement _target;
             private int _curIdx;
             private readonly int _endIdx;
 
+            /// <summary>
+            ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+            /// </summary>
             internal ArrayEnumerator(JsonElement target)
             {
                 Debug.Assert(target.TokenType == JsonTokenType.StartArray);
@@ -25,9 +31,17 @@ namespace System.Text.Json
                 _endIdx = _target._parent.GetEndIndex(_target._idx, includeEndElement: false);
             }
 
+            /// <inheritdoc />
             public JsonElement Current =>
                 _curIdx < 0 ? default : new JsonElement(_target._parent, _curIdx);
 
+            /// <summary>
+            ///   Returns an enumerator that iterates through a collection.
+            /// </summary>
+            /// <returns>
+            ///   An <see cref="ArrayEnumerator"/> value that can be used to iterate
+            ///   through the array.
+            /// </returns>
             public ArrayEnumerator GetEnumerator()
             {
                 ArrayEnumerator ator = this;
@@ -35,22 +49,28 @@ namespace System.Text.Json
                 return ator;
             }
 
+            /// <inheritdoc />
             IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+            /// <inheritdoc />
             IEnumerator<JsonElement> IEnumerable<JsonElement>.GetEnumerator() => GetEnumerator();
 
+            /// <inheritdoc />
             public void Dispose()
             {
                 _curIdx = _endIdx;
             }
 
+            /// <inheritdoc />
             public void Reset()
             {
                 _curIdx = -1;
             }
 
+            /// <inheritdoc />
             object IEnumerator.Current => Current;
 
+            /// <inheritdoc />
             public bool MoveNext()
             {
                 if (_curIdx >= _endIdx)

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ObjectEnumerator.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ObjectEnumerator.cs
index e89768c..8cad26d 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ObjectEnumerator.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.ObjectEnumerator.cs
@@ -10,12 +10,18 @@ namespace System.Text.Json
 {
     public partial struct JsonElement
     {
+        /// <summary>
+        ///   An enumerable and enumerator for the properties of a JSON object.
+        /// </summary>
         public struct ObjectEnumerator : IEnumerable<JsonProperty>, IEnumerator<JsonProperty>
         {
             private readonly JsonElement _target;
             private int _curIdx;
             private readonly int _endIdx;
 
+            /// <summary>
+            ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+            /// </summary>
             internal ObjectEnumerator(JsonElement target)
             {
                 Debug.Assert(target.TokenType == JsonTokenType.StartObject);
@@ -25,11 +31,25 @@ namespace System.Text.Json
                 _endIdx = _target._parent.GetEndIndex(_target._idx, includeEndElement: false);
             }
 
+            /// <inheritdoc />
             public JsonProperty Current =>
                 _curIdx < 0 ?
                     default :
                     new JsonProperty(new JsonElement(_target._parent, _curIdx));
 
+            /// <summary>
+            ///   Returns an enumerator that iterates the properties of an object.
+            /// </summary>
+            /// <returns>
+            ///   An <see cref="ObjectEnumerator"/> value that can be used to iterate
+            ///   through the object.
+            /// </returns>
+            /// <remarks>
+            ///   The enumerator will enumerate the properties in the order they are
+            ///   declared, and when an object has multiple definitions of a single
+            ///   property they will all individually be returned (each in the order
+            ///   they appear in the content).
+            /// </remarks>
             public ObjectEnumerator GetEnumerator()
             {
                 ObjectEnumerator ator = this;
@@ -37,22 +57,28 @@ namespace System.Text.Json
                 return ator;
             }
 
+            /// <inheritdoc />
             IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+            /// <inheritdoc />
             IEnumerator<JsonProperty> IEnumerable<JsonProperty>.GetEnumerator() => GetEnumerator();
 
+            /// <inheritdoc />
             public void Dispose()
             {
                 _curIdx = _endIdx;
             }
 
+            /// <inheritdoc />
             public void Reset()
             {
                 _curIdx = -1;
             }
 
+            /// <inheritdoc />
             object IEnumerator.Current => Current;
 
+            /// <inheritdoc />
             public bool MoveNext()
             {
                 if (_curIdx >= _endIdx)

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs
index dd5adf5..d5ed812 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonElement.cs
@@ -7,11 +7,17 @@ using System.Diagnostics;
 
 namespace System.Text.Json
 {
+    /// <summary>
+    ///   Represents a specific JSON value within a <see cref="JsonDocument"/>.
+    /// </summary>
     public readonly partial struct JsonElement
     {
         private readonly JsonDocument _parent;
         private readonly int _idx;
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal JsonElement(JsonDocument parent, int idx)
         {
             // parent is usually not null, but the Current property
@@ -23,10 +29,29 @@ namespace System.Text.Json
             _idx = idx;
         }
 
-        internal JsonTokenType TokenType => _parent?.GetJsonTokenType(_idx) ?? JsonTokenType.None;
+        private JsonTokenType TokenType => _parent?.GetJsonTokenType(_idx) ?? JsonTokenType.None;
 
+        /// <summary>
+        ///   The <see cref="JsonValueType"/> that the value is.
+        /// </summary>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public JsonValueType Type => TokenType.ToValueType();
 
+        /// <summary>
+        ///   Get the value at a specified index when the current value is a
+        ///   <see cref="JsonValueType.Array"/>.
+        /// </summary>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Array"/>.
+        /// </exception>
+        /// <exception cref="IndexOutOfRangeException">
+        ///   <paramref name="index"/> is not in the range [0, <see cref="GetArrayLength"/>()).
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public JsonElement this[int index]
         {
             get
@@ -37,6 +62,16 @@ namespace System.Text.Json
             }
         }
 
+        /// <summary>
+        ///   Get the number of values contained within the current array value.
+        /// </summary>
+        /// <returns>The number of values contained within the current array value.</returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Array"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public int GetArrayLength()
         {
             CheckValidInstance();
@@ -44,6 +79,33 @@ namespace System.Text.Json
             return _parent.GetArrayLength(_idx);
         }
 
+        /// <summary>
+        ///   Gets a <see cref="JsonElement"/> representing the value of a required property identified
+        ///   by <paramref name="propertyName"/>.
+        /// </summary>
+        /// <remarks>
+        ///   Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///
+        ///   If a property is defined multiple times for the same object, the last such definition is
+        ///   what is matched.
+        /// </remarks>
+        /// <param name="propertyName">Name of the property whose value to return.</param>
+        /// <returns>
+        ///   A <see cref="JsonElement"/> representing the value of the requested property.
+        /// </returns>
+        /// <seealso cref="EnumerateObject"/>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="KeyNotFoundException">
+        ///   No property was found with the requested name.
+        /// </exception>
+        /// <exception cref="ArgumentNullException">
+        ///   <paramref name="propertyName"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public JsonElement GetProperty(string propertyName)
         {
             if (propertyName == null)
@@ -57,6 +119,34 @@ namespace System.Text.Json
             throw new KeyNotFoundException();
         }
 
+        /// <summary>
+        ///   Gets a <see cref="JsonElement"/> representing the value of a required property identified
+        ///   by <paramref name="propertyName"/>.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     If a property is defined multiple times for the same object, the last such definition is
+        ///     what is matched.
+        ///   </para>
+        /// </remarks>
+        /// <param name="propertyName">Name of the property whose value to return.</param>
+        /// <returns>
+        ///   A <see cref="JsonElement"/> representing the value of the requested property.
+        /// </returns>
+        /// <seealso cref="EnumerateObject"/>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="KeyNotFoundException">
+        ///   No property was found with the requested name.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public JsonElement GetProperty(ReadOnlySpan<char> propertyName)
         {
             if (TryGetProperty(propertyName, out JsonElement property))
@@ -67,6 +157,36 @@ namespace System.Text.Json
             throw new KeyNotFoundException();
         }
 
+        /// <summary>
+        ///   Gets a <see cref="JsonElement"/> representing the value of a required property identified
+        ///   by <paramref name="utf8PropertyName"/>.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     If a property is defined multiple times for the same object, the last such definition is
+        ///     what is matched.
+        ///   </para>
+        /// </remarks>
+        /// <param name="utf8PropertyName">
+        ///   The UTF-8 (with no Byte-Order-Mark (BOM)) representation of the name of the property to return.
+        /// </param>
+        /// <returns>
+        ///   A <see cref="JsonElement"/> representing the value of the requested property.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="KeyNotFoundException">
+        ///   No property was found with the requested name.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
+        /// <seealso cref="EnumerateObject"/>
         public JsonElement GetProperty(ReadOnlySpan<byte> utf8PropertyName)
         {
             if (TryGetProperty(utf8PropertyName, out JsonElement property))
@@ -77,6 +197,36 @@ namespace System.Text.Json
             throw new KeyNotFoundException();
         }
 
+        /// <summary>
+        ///   Looks for a property named <paramref name="propertyName"/> in the current object, returning
+        ///   whether or not such a property existed. When the property exists <paramref name="value"/>
+        ///   is assigned to the value of that property.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     If a property is defined multiple times for the same object, the last such definition is
+        ///     what is matched.
+        ///   </para>
+        /// </remarks>
+        /// <param name="propertyName">Name of the property to find.</param>
+        /// <param name="value">Receives the value of the located property.</param>
+        /// <returns>
+        ///   <see langword="true"/> if the property was found, <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="ArgumentNullException">
+        ///   <paramref name="propertyName"/> is <see langword="null"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
+        /// <seealso cref="EnumerateObject"/>
         public bool TryGetProperty(string propertyName, out JsonElement value)
         {
             if (propertyName == null)
@@ -85,6 +235,33 @@ namespace System.Text.Json
             return TryGetProperty(propertyName.AsSpan(), out value);
         }
 
+        /// <summary>
+        ///   Looks for a property named <paramref name="propertyName"/> in the current object, returning
+        ///   whether or not such a property existed. When the property exists <paramref name="value"/>
+        ///   is assigned to the value of that property.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     If a property is defined multiple times for the same object, the last such definition is
+        ///     what is matched.
+        ///   </para>
+        /// </remarks>
+        /// <param name="propertyName">Name of the property to find.</param>
+        /// <param name="value">Receives the value of the located property.</param>
+        /// <returns>
+        ///   <see langword="true"/> if the property was found, <see langword="false"/> otherwise.
+        /// </returns>
+        /// <seealso cref="EnumerateObject"/>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetProperty(ReadOnlySpan<char> propertyName, out JsonElement value)
         {
             CheckValidInstance();
@@ -92,6 +269,35 @@ namespace System.Text.Json
             return _parent.TryGetNamedPropertyValue(_idx, propertyName, out value);
         }
 
+        /// <summary>
+        ///   Looks for a property named <paramref name="utf8PropertyName"/> in the current object, returning
+        ///   whether or not such a property existed. When the property exists <paramref name="value"/>
+        ///   is assigned to the value of that property.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     Property name matching is performed as an ordinal, case-sensitive, comparison.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     If a property is defined multiple times for the same object, the last such definition is
+        ///     what is matched.
+        ///   </para>
+        /// </remarks>
+        /// <param name="utf8PropertyName">
+        ///   The UTF-8 (with no Byte-Order-Mark (BOM)) representation of the name of the property to return.
+        /// </param>
+        /// <param name="value">Receives the value of the located property.</param>
+        /// <returns>
+        ///   <see langword="true"/> if the property was found, <see langword="false"/> otherwise.
+        /// </returns>
+        /// <seealso cref="EnumerateObject"/>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetProperty(ReadOnlySpan<byte> utf8PropertyName, out JsonElement value)
         {
             CheckValidInstance();
@@ -99,6 +305,20 @@ namespace System.Text.Json
             return _parent.TryGetNamedPropertyValue(_idx, utf8PropertyName, out value);
         }
 
+        /// <summary>
+        ///   Gets the value of the element as a <see cref="bool"/>.
+        /// </summary>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>The value of the element as a <see cref="bool"/>.</returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is neither <see cref="JsonValueType.True"/> or
+        ///   <see cref="JsonValueType.False"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool GetBoolean()
         {
             // CheckValidInstance is redundant.  Asking for the type will
@@ -112,6 +332,20 @@ namespace System.Text.Json
                 throw ThrowHelper.GetJsonElementWrongTypeException(nameof(Boolean), type);
         }
 
+        /// <summary>
+        ///   Gets the value of the element as a <see cref="string"/>.
+        /// </summary>
+        /// <remarks>
+        ///   This method does not create a string representation of values other than JSON strings.
+        /// </remarks>
+        /// <returns>The value of the element as a <see cref="bool"/>.</returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.String"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
+        /// <seealso cref="ToString"/>
         public string GetString()
         {
             CheckValidInstance();
@@ -119,6 +353,23 @@ namespace System.Text.Json
             return _parent.GetString(_idx, JsonTokenType.String);
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as an <see cref="int"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as an <see cref="int"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetInt32(out int value)
         {
             CheckValidInstance();
@@ -126,6 +377,19 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as an <see cref="int"/>.
+        /// </summary>
+        /// <returns>The current JSON number as an <see cref="int"/>.</returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as an <see cref="int"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public int GetInt32()
         {
             if (TryGetInt32(out int value))
@@ -136,6 +400,23 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="uint"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="uint"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         [CLSCompliant(false)]
         public bool TryGetUInt32(out uint value)
         {
@@ -144,6 +425,22 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="uint"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="uint"/>.</returns>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="uint"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         [CLSCompliant(false)]
         public uint GetUInt32()
         {
@@ -155,6 +452,23 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="long"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="long"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetInt64(out long value)
         {
             CheckValidInstance();
@@ -162,6 +476,22 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="long"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="long"/>.</returns>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="long"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public long GetInt64()
         {
             if (TryGetInt64(out long value))
@@ -172,6 +502,23 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="ulong"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="ulong"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         [CLSCompliant(false)]
         public bool TryGetUInt64(out ulong value)
         {
@@ -180,6 +527,22 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="ulong"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="ulong"/>.</returns>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="ulong"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         [CLSCompliant(false)]
         public ulong GetUInt64()
         {
@@ -191,6 +554,32 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="double"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   <para>
+        ///     This method does not parse the contents of a JSON string value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     On .NET Core this method does not return <see langword="false"/> for values larger than
+        ///     <see cref="double.MaxValue"/> (or smaller than <see cref="double.MinValue"/>),
+        ///     instead <see langword="true"/> is returned and <see cref="double.PositiveInfinity"/> (or
+        ///     <see cref="double.NegativeInfinity"/>) is emitted.
+        ///   </para>
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="double"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetDouble(out double value)
         {
             CheckValidInstance();
@@ -198,6 +587,30 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="double"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="double"/>.</returns>
+        /// <remarks>
+        ///   <para>
+        ///     This method does not parse the contents of a JSON string value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     On .NET Core this method returns <see cref="double.PositiveInfinity"/> (or
+        ///     <see cref="double.NegativeInfinity"/>) for values larger than
+        ///     <see cref="double.MaxValue"/> (or smaller than <see cref="double.MinValue"/>).
+        ///   </para>
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="double"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public double GetDouble()
         {
             if (TryGetDouble(out double value))
@@ -208,6 +621,32 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="float"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   <para>
+        ///     This method does not parse the contents of a JSON string value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     On .NET Core this method does not return <see langword="false"/> for values larger than
+        ///     <see cref="float.MaxValue"/> (or smaller than <see cref="float.MinValue"/>),
+        ///     instead <see langword="true"/> is returned and <see cref="float.PositiveInfinity"/> (or
+        ///     <see cref="float.NegativeInfinity"/>) is emitted.
+        ///   </para>
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="float"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public bool TryGetSingle(out float value)
         {
             CheckValidInstance();
@@ -215,6 +654,30 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="float"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="float"/>.</returns>
+        /// <remarks>
+        ///   <para>
+        ///     This method does not parse the contents of a JSON string value.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     On .NET Core this method returns <see cref="float.PositiveInfinity"/> (or
+        ///     <see cref="float.NegativeInfinity"/>) for values larger than
+        ///     <see cref="float.MaxValue"/> (or smaller than <see cref="float.MinValue"/>).
+        ///   </para>
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="float"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public float GetSingle()
         {
             if (TryGetSingle(out float value))
@@ -225,6 +688,24 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   Attempts to represent the current JSON number as a <see cref="decimal"/>.
+        /// </summary>
+        /// <param name="value">Receives the value.</param>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <returns>
+        ///   <see langword="true"/> if the number can be represented as a <see cref="decimal"/>,
+        ///   <see langword="false"/> otherwise.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
+        /// <seealso cref="GetRawText"/>
         public bool TryGetDecimal(out decimal value)
         {
             CheckValidInstance();
@@ -232,6 +713,23 @@ namespace System.Text.Json
             return _parent.TryGetValue(_idx, out value);
         }
 
+        /// <summary>
+        ///   Gets the current JSON number as a <see cref="decimal"/>.
+        /// </summary>
+        /// <returns>The current JSON number as a <see cref="decimal"/>.</returns>
+        /// <remarks>
+        ///   This method does not parse the contents of a JSON string value.
+        /// </remarks>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Number"/>.
+        /// </exception>
+        /// <exception cref="FormatException">
+        ///   The value cannot be represented as a <see cref="decimal"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
+        /// <seealso cref="GetRawText"/>
         public decimal GetDecimal()
         {
             if (TryGetDecimal(out decimal value))
@@ -242,6 +740,9 @@ namespace System.Text.Json
             throw new FormatException();
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetPropertyName()
         {
             CheckValidInstance();
@@ -249,6 +750,15 @@ namespace System.Text.Json
             return _parent.GetNameOfPropertyValue(_idx);
         }
 
+        /// <summary>
+        ///   Gets the original input data backing this value, returning it as a <see cref="string"/>.
+        /// </summary>
+        /// <returns>
+        ///  The original input data backing this value, returning it as a <see cref="string"/>.
+        /// </returns>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public string GetRawText()
         {
             CheckValidInstance();
@@ -256,6 +766,9 @@ namespace System.Text.Json
             return _parent.GetRawValueAsString(_idx);
         }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal string GetPropertyRawText()
         {
             CheckValidInstance();
@@ -263,6 +776,18 @@ namespace System.Text.Json
             return _parent.GetPropertyRawValueAsString(_idx);
         }
 
+        /// <summary>
+        ///   Get an enumerator to enumerate the values in the JSON array represented by this JsonElement.
+        /// </summary>
+        /// <returns>
+        ///   An enumerator to enumerate the values in the JSON array represented by this JsonElement.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Array"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public ArrayEnumerator EnumerateArray()
         {
             CheckValidInstance();
@@ -277,6 +802,18 @@ namespace System.Text.Json
             return new ArrayEnumerator(this);
         }
 
+        /// <summary>
+        ///   Get an enumerator to enumerate the properties in the JSON object represented by this JsonElement.
+        /// </summary>
+        /// <returns>
+        ///   An enumerator to enumerate the properties in the JSON object represented by this JsonElement.
+        /// </returns>
+        /// <exception cref="InvalidOperationException">
+        ///   This value's <see cref="Type"/> is not <see cref="JsonValueType.Object"/>.
+        /// </exception>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public ObjectEnumerator EnumerateObject()
         {
             CheckValidInstance();
@@ -291,6 +828,36 @@ namespace System.Text.Json
             return new ObjectEnumerator(this);
         }
 
+        /// <summary>
+        ///   Gets a string representation for the current value appropriate to the value type.
+        /// </summary>
+        /// <remarks>
+        ///   <para>
+        ///     For <see cref="JsonValueType.Null"/>, <see cref="string.Empty"/> is returned.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     For <see cref="JsonValueType.True"/>, <see cref="bool.TrueString"/> is returned.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     For <see cref="JsonValueType.False"/>, <see cref="bool.FalseString"/> is returned.
+        ///   </para>
+        /// 
+        ///   <para>
+        ///     For <see cref="JsonValueType.String"/>, the value of <see cref="GetString"/>() is returned.
+        ///   </para>
+        ///
+        ///   <para>
+        ///     For other types, the value of <see cref="GetRawText"/>() is returned.
+        ///   </para>
+        /// </remarks>
+        /// <returns>
+        ///   A string representation for the current value appropriate to the value type.
+        /// </returns>
+        /// <exception cref="ObjectDisposedException">
+        ///   The parent <see cref="JsonDocument"/> has been disposed.
+        /// </exception>
         public override string ToString()
         {
             switch (TokenType)

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonProperty.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonProperty.cs
index ee3a6f8..f4d5bb2 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonProperty.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonProperty.cs
@@ -4,17 +4,38 @@
 
 namespace System.Text.Json
 {
+    /// <summary>
+    ///   Represents a single property for a JSON object.
+    /// </summary>
     public readonly struct JsonProperty
     {
+        /// <summary>
+        ///   The value of this property.
+        /// </summary>
         public JsonElement Value { get; }
 
+        /// <summary>
+        ///   This is an implementation detail and MUST NOT be called by source-package consumers.
+        /// </summary>
         internal JsonProperty(JsonElement value)
         {
             Value = value;
         }
 
+        /// <summary>
+        ///   The name of this property.
+        /// </summary>
         public string Name => Value.GetPropertyName();
 
+        /// <summary>
+        ///   Provides a <see cref="string"/> representation of the property for
+        ///   debugging purposes.
+        /// </summary>
+        /// <returns>
+        ///   A string containing the un-interpreted value of the property, beginning
+        ///   at the declaring open-quote and ending at the last character that is part of
+        ///   the value.
+        /// </returns>
         public override string ToString()
         {
             return Value.GetPropertyRawText();

diff --git a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonValueType.cs b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonValueType.cs
index 6f6dc41..18240bc 100644 (file)
--- a/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonValueType.cs
+++ b/src/libraries/System.Text.Json/src/System/Text/Json/Document/JsonValueType.cs
@@ -4,15 +4,49 @@
 
 namespace System.Text.Json
 {
+    /// <summary>
+    ///   Specifies the data type of a JSON value.
+    /// </summary>
     public enum JsonValueType : byte
     {
+        /// <summary>
+        ///   Indicates that there is no value (as distinct from <see cref="Null"/>).
+        /// </summary>
         Undefined,
+
+        /// <summary>
+        ///   Indicates that a value is a JSON object.
+        /// </summary>
         Object,
+
+        /// <summary>
+        ///   Indicates that a value is a JSON array.
+        /// </summary>
         Array,
+
+        /// <summary>
+        ///   Indicates that a value is a JSON string.
+        /// </summary>
         String,
+
+        /// <summary>
+        ///   Indicates that a value is a JSON number.
+        /// </summary>
         Number,
+
+        /// <summary>
+        ///   Indicates that a value is the JSON value <c>true</c>.
+        /// </summary>
         True,
+
+        /// <summary>
+        ///   Indicates that a value is the JSON value <c>false</c>.
+        /// </summary>
         False,
+
+        /// <summary>
+        ///   Indicates that a value is the JSON value <c>null</c>.
+        /// </summary>
         Null,
     }
 }