Document everything, and turn on errors if we fail to document anything in the future.
diff --git a/csharp/src/Google.Protobuf/ByteString.cs b/csharp/src/Google.Protobuf/ByteString.cs
index cf5468d..2aa6248 100644
--- a/csharp/src/Google.Protobuf/ByteString.cs
+++ b/csharp/src/Google.Protobuf/ByteString.cs
@@ -105,23 +105,35 @@
get { return bytes.Length; }
}
+ /// <summary>
+ /// Returns <c>true</c> if this byte string is empty, <c>false</c> otherwise.
+ /// </summary>
public bool IsEmpty
{
get { return Length == 0; }
}
+ /// <summary>
+ /// Converts this <see cref="ByteString"/> into a byte array.
+ /// </summary>
+ /// <remarks>The data is copied - changes to the returned array will not be reflected in this <c>ByteString</c>.</remarks>
+ /// <returns>A byte array with the same data as this <c>ByteString</c>.</returns>
public byte[] ToByteArray()
{
return (byte[]) bytes.Clone();
}
+ /// <summary>
+ /// Converts this <see cref="ByteString"/> into a standard base64 representation.
+ /// </summary>
+ /// <returns>A base64 representation of this <c>ByteString</c>.</returns>
public string ToBase64()
{
return Convert.ToBase64String(bytes);
}
/// <summary>
- /// Constructs a ByteString from the Base64 Encoded String.
+ /// Constructs a <see cref="ByteString" /> from the Base64 Encoded String.
/// </summary>
public static ByteString FromBase64(string bytes)
{
@@ -131,7 +143,7 @@
}
/// <summary>
- /// Constructs a ByteString from the given array. The contents
+ /// Constructs a <see cref="ByteString" /> from the given array. The contents
/// are copied, so further modifications to the array will not
/// be reflected in the returned ByteString.
/// This method can also be invoked in <c>ByteString.CopyFrom(0xaa, 0xbb, ...)</c> form
@@ -143,7 +155,7 @@
}
/// <summary>
- /// Constructs a ByteString from a portion of a byte array.
+ /// Constructs a <see cref="ByteString" /> from a portion of a byte array.
/// </summary>
public static ByteString CopyFrom(byte[] bytes, int offset, int count)
{
@@ -153,7 +165,7 @@
}
/// <summary>
- /// Creates a new ByteString by encoding the specified text with
+ /// Creates a new <see cref="ByteString" /> by encoding the specified text with
/// the given encoding.
/// </summary>
public static ByteString CopyFrom(string text, Encoding encoding)
@@ -162,7 +174,7 @@
}
/// <summary>
- /// Creates a new ByteString by encoding the specified text in UTF-8.
+ /// Creates a new <see cref="ByteString" /> by encoding the specified text in UTF-8.
/// </summary>
public static ByteString CopyFromUtf8(string text)
{
@@ -177,21 +189,46 @@
get { return bytes[index]; }
}
+ /// <summary>
+ /// Converts this <see cref="ByteString"/> into a string by applying the given encoding.
+ /// </summary>
+ /// <remarks>
+ /// This method should only be used to convert binary data which was the result of encoding
+ /// text with the given encoding.
+ /// </remarks>
+ /// <param name="encoding">The encoding to use to decode the binary data into text.</param>
+ /// <returns>The result of decoding the binary data with the given decoding.</returns>
public string ToString(Encoding encoding)
{
return encoding.GetString(bytes, 0, bytes.Length);
}
+ /// <summary>
+ /// Converts this <see cref="ByteString"/> into a string by applying the UTF-8 encoding.
+ /// </summary>
+ /// <remarks>
+ /// This method should only be used to convert binary data which was the result of encoding
+ /// text with UTF-8.
+ /// </remarks>
+ /// <returns>The result of decoding the binary data with the given decoding.</returns>
public string ToStringUtf8()
{
return ToString(Encoding.UTF8);
}
+ /// <summary>
+ /// Returns an iterator over the bytes in this <see cref="ByteString"/>.
+ /// </summary>
+ /// <returns>An iterator over the bytes in this object.</returns>
public IEnumerator<byte> GetEnumerator()
{
return ((IEnumerable<byte>) bytes).GetEnumerator();
}
+ /// <summary>
+ /// Returns an iterator over the bytes in this <see cref="ByteString"/>.
+ /// </summary>
+ /// <returns>An iterator over the bytes in this object.</returns>
IEnumerator IEnumerable.GetEnumerator()
{
return GetEnumerator();
@@ -206,6 +243,12 @@
return new CodedInputStream(bytes);
}
+ /// <summary>
+ /// Compares two byte strings for equality.
+ /// </summary>
+ /// <param name="lhs">The first byte string to compare.</param>
+ /// <param name="rhs">The second byte string to compare.</param>
+ /// <returns><c>true</c> if the byte strings are equal; false otherwise.</returns>
public static bool operator ==(ByteString lhs, ByteString rhs)
{
if (ReferenceEquals(lhs, rhs))
@@ -230,6 +273,12 @@
return true;
}
+ /// <summary>
+ /// Compares two byte strings for inequality.
+ /// </summary>
+ /// <param name="lhs">The first byte string to compare.</param>
+ /// <param name="rhs">The second byte string to compare.</param>
+ /// <returns><c>false</c> if the byte strings are equal; true otherwise.</returns>
public static bool operator !=(ByteString lhs, ByteString rhs)
{
return !(lhs == rhs);
@@ -237,11 +286,21 @@
// TODO(jonskeet): CopyTo if it turns out to be required
+ /// <summary>
+ /// Compares this byte string with another object.
+ /// </summary>
+ /// <param name="obj">The object to compare this with.</param>
+ /// <returns><c>true</c> if <paramref name="obj"/> refers to an equal <see cref="ByteString"/>; <c>false</c> otherwise.</returns>
public override bool Equals(object obj)
{
return this == (obj as ByteString);
}
+ /// <summary>
+ /// Returns a hash code for this object. Two equal byte strings
+ /// will return the same hash code.
+ /// </summary>
+ /// <returns>A hash code for this object.</returns>
public override int GetHashCode()
{
int ret = 23;
@@ -252,6 +311,11 @@
return ret;
}
+ /// <summary>
+ /// Compares this byte string with another.
+ /// </summary>
+ /// <param name="other">The <see cref="ByteString"/> to compare this with.</param>
+ /// <returns><c>true</c> if <paramref name="other"/> refers to an equal byte string; <c>false</c> otherwise.</returns>
public bool Equals(ByteString other)
{
return this == other;
diff --git a/csharp/src/Google.Protobuf/CodedInputStream.cs b/csharp/src/Google.Protobuf/CodedInputStream.cs
index f2e1d66..a1abfcb 100644
--- a/csharp/src/Google.Protobuf/CodedInputStream.cs
+++ b/csharp/src/Google.Protobuf/CodedInputStream.cs
@@ -66,7 +66,7 @@
internal const int DefaultRecursionLimit = 64;
internal const int DefaultSizeLimit = 64 << 20; // 64MB
- public const int BufferSize = 4096;
+ internal const int BufferSize = 4096;
/// <summary>
/// The total number of bytes read before the current buffer. The
diff --git a/csharp/src/Google.Protobuf/CodedOutputStream.cs b/csharp/src/Google.Protobuf/CodedOutputStream.cs
index b084c14..08ea700 100644
--- a/csharp/src/Google.Protobuf/CodedOutputStream.cs
+++ b/csharp/src/Google.Protobuf/CodedOutputStream.cs
@@ -297,6 +297,10 @@
WriteInt32(value);
}
+ /// <summary>
+ /// Writes an sfixed32 value, without a tag, to the stream.
+ /// </summary>
+ /// <param name="value">The value to write.</param>
public void WriteSFixed32(int value)
{
WriteRawLittleEndian32((uint) value);
@@ -649,6 +653,9 @@
}
}
+ /// <summary>
+ /// Flushes any buffered data to the underlying stream (if there is one).
+ /// </summary>
public void Flush()
{
if (output != null)
diff --git a/csharp/src/Google.Protobuf/Collections/MapField.cs b/csharp/src/Google.Protobuf/Collections/MapField.cs
index fc94fd5..fed3d06 100644
--- a/csharp/src/Google.Protobuf/Collections/MapField.cs
+++ b/csharp/src/Google.Protobuf/Collections/MapField.cs
@@ -42,14 +42,14 @@
/// <summary>
/// Representation of a map field in a Protocol Buffer message.
/// </summary>
+ /// <typeparam name="TKey">Key type in the map. Must be a type supported by Protocol Buffer map keys.</typeparam>
+ /// <typeparam name="TValue">Value type in the map. Must be a type supported by Protocol Buffers.</typeparam>
/// <remarks>
/// This implementation preserves insertion order for simplicity of testing
/// code using maps fields. Overwriting an existing entry does not change the
/// position of that entry within the map. Equality is not order-sensitive.
- /// For string keys, the equality comparison is provided by <see cref="StringComparer.Ordinal"/>.
+ /// For string keys, the equality comparison is provided by <see cref="StringComparer.Ordinal" />.
/// </remarks>
- /// <typeparam name="TKey">Key type in the map. Must be a type supported by Protocol Buffer map keys.</typeparam>
- /// <typeparam name="TValue">Value type in the map. Must be a type supported by Protocol Buffers.</typeparam>
public sealed class MapField<TKey, TValue> : IDeepCloneable<MapField<TKey, TValue>>, IDictionary<TKey, TValue>, IEquatable<MapField<TKey, TValue>>, IDictionary
{
// TODO: Don't create the map/list until we have an entry. (Assume many maps will be empty.)
@@ -81,6 +81,12 @@
this.allowNullValues = allowNullValues;
}
+ /// <summary>
+ /// Creates a deep clone of this object.
+ /// </summary>
+ /// <returns>
+ /// A deep clone of this object.
+ /// </returns>
public MapField<TKey, TValue> Clone()
{
var clone = new MapField<TKey, TValue>(allowNullValues);
@@ -100,6 +106,15 @@
return clone;
}
+ /// <summary>
+ /// Adds the specified key/value pair to the map.
+ /// </summary>
+ /// <remarks>
+ /// This operation fails if the key already exists in the map. To replace an existing entry, use the indexer.
+ /// </remarks>
+ /// <param name="key">The key to add</param>
+ /// <param name="value">The value to add.</param>
+ /// <exception cref="System.ArgumentException">The given key already exists in map.</exception>
public void Add(TKey key, TValue value)
{
// Validation of arguments happens in ContainsKey and the indexer
@@ -110,12 +125,22 @@
this[key] = value;
}
+ /// <summary>
+ /// Determines whether the specified key is present in the map.
+ /// </summary>
+ /// <param name="key">The key to check.</param>
+ /// <returns><c>true</c> if the map contains the given key; <c>false</c> otherwise.</returns>
public bool ContainsKey(TKey key)
{
Preconditions.CheckNotNullUnconstrained(key, "key");
return map.ContainsKey(key);
}
+ /// <summary>
+ /// Removes the entry identified by the given key from the map.
+ /// </summary>
+ /// <param name="key">The key indicating the entry to remove from the map.</param>
+ /// <returns><c>true</c> if the map contained the given key before the entry was removed; <c>false</c> otherwise.</returns>
public bool Remove(TKey key)
{
Preconditions.CheckNotNullUnconstrained(key, "key");
@@ -132,6 +157,14 @@
}
}
+ /// <summary>
+ /// Gets the value associated with the specified key.
+ /// </summary>
+ /// <param name="key">The key whose value to get.</param>
+ /// <param name="value">When this method returns, the value associated with the specified key, if the key is found;
+ /// otherwise, the default value for the type of the <paramref name="value"/> parameter.
+ /// This parameter is passed uninitialized.</param>
+ /// <returns><c>true</c> if the map contains an element with the specified key; otherwise, <c>false</c>.</returns>
public bool TryGetValue(TKey key, out TValue value)
{
LinkedListNode<KeyValuePair<TKey, TValue>> node;
@@ -147,6 +180,13 @@
}
}
+ /// <summary>
+ /// Gets or sets the value associated with the specified key.
+ /// </summary>
+ /// <param name="key">The key of the value to get or set.</param>
+ /// <exception cref="KeyNotFoundException">The property is retrieved and key does not exist in the collection.</exception>
+ /// <returns>The value associated with the specified key. If the specified key is not found,
+ /// a get operation throws a <see cref="KeyNotFoundException"/>, and a set operation creates a new element with the specified key.</returns>
public TValue this[TKey key]
{
get
@@ -182,9 +222,21 @@
}
// TODO: Make these views?
+
+ /// <summary>
+ /// Gets a collection containing the keys in the map.
+ /// </summary>
public ICollection<TKey> Keys { get { return list.Select(t => t.Key).ToList(); } }
+
+ /// <summary>
+ /// Gets a collection containing the values in the map.
+ /// </summary>
public ICollection<TValue> Values { get { return list.Select(t => t.Value).ToList(); } }
+ /// <summary>
+ /// Adds the specified entries to the map.
+ /// </summary>
+ /// <param name="entries">The entries to add to the map.</param>
public void Add(IDictionary<TKey, TValue> entries)
{
Preconditions.CheckNotNull(entries, "entries");
@@ -194,27 +246,51 @@
}
}
+ /// <summary>
+ /// Returns an enumerator that iterates through the collection.
+ /// </summary>
+ /// <returns>
+ /// An enumerator that can be used to iterate through the collection.
+ /// </returns>
public IEnumerator<KeyValuePair<TKey, TValue>> GetEnumerator()
{
return list.GetEnumerator();
}
+ /// <summary>
+ /// Returns an enumerator that iterates through a collection.
+ /// </summary>
+ /// <returns>
+ /// An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.
+ /// </returns>
IEnumerator IEnumerable.GetEnumerator()
{
return GetEnumerator();
}
+ /// <summary>
+ /// Adds the specified item to the map.
+ /// </summary>
+ /// <param name="item">The item to add to the map.</param>
void ICollection<KeyValuePair<TKey, TValue>>.Add(KeyValuePair<TKey, TValue> item)
{
Add(item.Key, item.Value);
}
+ /// <summary>
+ /// Removes all items from the map.
+ /// </summary>
public void Clear()
{
list.Clear();
map.Clear();
}
+ /// <summary>
+ /// Determines whether map contains an entry equivalent to the given key/value pair.
+ /// </summary>
+ /// <param name="item">The key/value pair to find.</param>
+ /// <returns></returns>
bool ICollection<KeyValuePair<TKey, TValue>>.Contains(KeyValuePair<TKey, TValue> item)
{
TValue value;
@@ -222,11 +298,22 @@
&& EqualityComparer<TValue>.Default.Equals(item.Value, value);
}
+ /// <summary>
+ /// Copies the key/value pairs in this map to an array.
+ /// </summary>
+ /// <param name="array">The array to copy the entries into.</param>
+ /// <param name="arrayIndex">The index of the array at which to start copying values.</param>
void ICollection<KeyValuePair<TKey, TValue>>.CopyTo(KeyValuePair<TKey, TValue>[] array, int arrayIndex)
{
list.CopyTo(array, arrayIndex);
}
+ /// <summary>
+ /// Removes the specified key/value pair from the map.
+ /// </summary>
+ /// <remarks>Both the key and the value must be found for the entry to be removed.</remarks>
+ /// <param name="item">The key/value pair to remove.</param>
+ /// <returns><c>true</c> if the key/value pair was found and removed; <c>false</c> otherwise.</returns>
bool ICollection<KeyValuePair<TKey, TValue>>.Remove(KeyValuePair<TKey, TValue> item)
{
if (item.Key == null)
@@ -252,14 +339,34 @@
/// </summary>
public bool AllowsNullValues { get { return allowNullValues; } }
+ /// <summary>
+ /// Gets the number of elements contained in the map.
+ /// </summary>
public int Count { get { return list.Count; } }
+
+ /// <summary>
+ /// Gets a value indicating whether the map is read-only.
+ /// </summary>
public bool IsReadOnly { get { return false; } }
+ /// <summary>
+ /// Determines whether the specified <see cref="System.Object" />, is equal to this instance.
+ /// </summary>
+ /// <param name="other">The <see cref="System.Object" /> to compare with this instance.</param>
+ /// <returns>
+ /// <c>true</c> if the specified <see cref="System.Object" /> is equal to this instance; otherwise, <c>false</c>.
+ /// </returns>
public override bool Equals(object other)
{
return Equals(other as MapField<TKey, TValue>);
}
+ /// <summary>
+ /// Returns a hash code for this instance.
+ /// </summary>
+ /// <returns>
+ /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.
+ /// </returns>
public override int GetHashCode()
{
var valueComparer = EqualityComparer<TValue>.Default;
@@ -271,6 +378,14 @@
return hash;
}
+ /// <summary>
+ /// Compares this map with another for equality.
+ /// </summary>
+ /// <remarks>
+ /// The order of the key/value pairs in the maps is not deemed significant in this comparison.
+ /// </remarks>
+ /// <param name="other">The map to compare this with.</param>
+ /// <returns><c>true</c> if <paramref name="other"/> refers to an equal map; <c>false</c> otherwise.</returns>
public bool Equals(MapField<TKey, TValue> other)
{
if (other == null)
@@ -322,6 +437,12 @@
} while (input.MaybeConsumeTag(codec.MapTag));
}
+ /// <summary>
+ /// Writes the contents of this map to the given coded output stream, using the specified codec
+ /// to encode each entry.
+ /// </summary>
+ /// <param name="output">The output stream to write to.</param>
+ /// <param name="codec">The codec to use for each entry.</param>
public void WriteTo(CodedOutputStream output, Codec codec)
{
var message = new Codec.MessageAdapter(codec);
@@ -334,6 +455,11 @@
}
}
+ /// <summary>
+ /// Calculates the size of this map based on the given entry codec.
+ /// </summary>
+ /// <param name="codec">The codec to use to encode each entry.</param>
+ /// <returns></returns>
public int CalculateSize(Codec codec)
{
if (Count == 0)
@@ -446,7 +572,7 @@
}
/// <summary>
- /// A codec for a specific map field. This contains all the information required to encoded and
+ /// A codec for a specific map field. This contains all the information required to encode and
/// decode the nested messages.
/// </summary>
public sealed class Codec
@@ -455,6 +581,13 @@
private readonly FieldCodec<TValue> valueCodec;
private readonly uint mapTag;
+ /// <summary>
+ /// Creates a new entry codec based on a separate key codec and value codec,
+ /// and the tag to use for each map entry.
+ /// </summary>
+ /// <param name="keyCodec">The key codec.</param>
+ /// <param name="valueCodec">The value codec.</param>
+ /// <param name="mapTag">The map tag to use to introduce each map entry.</param>
public Codec(FieldCodec<TKey> keyCodec, FieldCodec<TValue> valueCodec, uint mapTag)
{
this.keyCodec = keyCodec;
diff --git a/csharp/src/Google.Protobuf/Collections/RepeatedField.cs b/csharp/src/Google.Protobuf/Collections/RepeatedField.cs
index 3ce19c8..c901864 100644
--- a/csharp/src/Google.Protobuf/Collections/RepeatedField.cs
+++ b/csharp/src/Google.Protobuf/Collections/RepeatedField.cs
@@ -30,7 +30,6 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
-using Google.Protobuf.Reflection;
using System;
using System.Collections;
using System.Collections.Generic;
@@ -81,6 +80,11 @@
return clone;
}
+ /// <summary>
+ /// Adds the entries from the given input stream, decoding them with the specified codec.
+ /// </summary>
+ /// <param name="input">The input stream to read from.</param>
+ /// <param name="codec">The codec to use in order to read each entry.</param>
public void AddEntriesFrom(CodedInputStream input, FieldCodec<T> codec)
{
// TODO: Inline some of the Add code, so we can avoid checking the size on every
@@ -112,6 +116,12 @@
}
}
+ /// <summary>
+ /// Calculates the size of this collection based on the given codec.
+ /// </summary>
+ /// <param name="codec">The codec to use when encoding each field.</param>
+ /// <returns>The number of bytes that would be written to a <see cref="CodedOutputStream"/> by <see cref="WriteTo"/>,
+ /// using the same codec.</returns>
public int CalculateSize(FieldCodec<T> codec)
{
if (count == 0)
@@ -157,6 +167,12 @@
}
}
+ /// <summary>
+ /// Writes the contents of this collection to the given <see cref="CodedOutputStream"/>,
+ /// encoding each value using the specified codec.
+ /// </summary>
+ /// <param name="output">The output stream to write to.</param>
+ /// <param name="codec">The codec to use when encoding each value.</param>
public void WriteTo(CodedOutputStream output, FieldCodec<T> codec)
{
if (count == 0)
@@ -200,6 +216,10 @@
}
}
+ /// <summary>
+ /// Adds the specified item to the collection.
+ /// </summary>
+ /// <param name="item">The item to add.</param>
public void Add(T item)
{
if (item == null)
@@ -210,22 +230,40 @@
array[count++] = item;
}
+ /// <summary>
+ /// Removes all items from the collection.
+ /// </summary>
public void Clear()
{
array = EmptyArray;
count = 0;
}
+ /// <summary>
+ /// Determines whether this collection contains the given item.
+ /// </summary>
+ /// <param name="item">The item to find.</param>
+ /// <returns><c>true</c> if this collection contains the given item; <c>false</c> otherwise.</returns>
public bool Contains(T item)
{
return IndexOf(item) != -1;
}
+ /// <summary>
+ /// Copies this collection to the given array.
+ /// </summary>
+ /// <param name="array">The array to copy to.</param>
+ /// <param name="arrayIndex">The first index of the array to copy to.</param>
public void CopyTo(T[] array, int arrayIndex)
{
Array.Copy(this.array, 0, array, arrayIndex, count);
}
+ /// <summary>
+ /// Removes the specified item from the collection
+ /// </summary>
+ /// <param name="item">The item to remove.</param>
+ /// <returns><c>true</c> if the item was found and removed; <c>false</c> otherwise.</returns>
public bool Remove(T item)
{
int index = IndexOf(item);
@@ -239,10 +277,22 @@
return true;
}
+ /// <summary>
+ /// Gets the number of elements contained in the collection.
+ /// </summary>
public int Count { get { return count; } }
+ /// <summary>
+ /// Gets a value indicating whether the collection is read-only.
+ /// </summary>
public bool IsReadOnly { get { return false; } }
+ // TODO: Remove this overload and just handle it in the one below, at execution time?
+
+ /// <summary>
+ /// Adds all of the specified values into this collection.
+ /// </summary>
+ /// <param name="values">The values to add to this collection.</param>
public void Add(RepeatedField<T> values)
{
if (values == null)
@@ -255,6 +305,10 @@
count += values.count;
}
+ /// <summary>
+ /// Adds all of the specified values into this collection.
+ /// </summary>
+ /// <param name="values">The values to add to this collection.</param>
public void Add(IEnumerable<T> values)
{
if (values == null)
@@ -268,6 +322,12 @@
}
}
+ /// <summary>
+ /// Returns an enumerator that iterates through the collection.
+ /// </summary>
+ /// <returns>
+ /// An enumerator that can be used to iterate through the collection.
+ /// </returns>
public IEnumerator<T> GetEnumerator()
{
for (int i = 0; i < count; i++)
@@ -276,16 +336,35 @@
}
}
+ /// <summary>
+ /// Determines whether the specified <see cref="System.Object" />, is equal to this instance.
+ /// </summary>
+ /// <param name="obj">The <see cref="System.Object" /> to compare with this instance.</param>
+ /// <returns>
+ /// <c>true</c> if the specified <see cref="System.Object" /> is equal to this instance; otherwise, <c>false</c>.
+ /// </returns>
public override bool Equals(object obj)
{
return Equals(obj as RepeatedField<T>);
}
+ /// <summary>
+ /// Returns an enumerator that iterates through a collection.
+ /// </summary>
+ /// <returns>
+ /// An <see cref="T:System.Collections.IEnumerator" /> object that can be used to iterate through the collection.
+ /// </returns>
IEnumerator IEnumerable.GetEnumerator()
{
return GetEnumerator();
- }
+ }
+ /// <summary>
+ /// Returns a hash code for this instance.
+ /// </summary>
+ /// <returns>
+ /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table.
+ /// </returns>
public override int GetHashCode()
{
int hash = 0;
@@ -296,6 +375,11 @@
return hash;
}
+ /// <summary>
+ /// Compares this repeated field with another for equality.
+ /// </summary>
+ /// <param name="other">The repeated field to compare this with.</param>
+ /// <returns><c>true</c> if <paramref name="other"/> refers to an equal repeated field; <c>false</c> otherwise.</returns>
public bool Equals(RepeatedField<T> other)
{
if (ReferenceEquals(other, null))
@@ -322,6 +406,12 @@
return true;
}
+ /// <summary>
+ /// Returns the index of the given item within the collection, or -1 if the item is not
+ /// present.
+ /// </summary>
+ /// <param name="item">The item to find in the collection.</param>
+ /// <returns>The zero-based index of the item, or -1 if it is not found.</returns>
public int IndexOf(T item)
{
if (item == null)
@@ -340,6 +430,11 @@
return -1;
}
+ /// <summary>
+ /// Inserts the given item at the specified index.
+ /// </summary>
+ /// <param name="index">The index at which to insert the item.</param>
+ /// <param name="item">The item to insert.</param>
public void Insert(int index, T item)
{
if (item == null)
@@ -356,6 +451,10 @@
count++;
}
+ /// <summary>
+ /// Removes the item at the given index.
+ /// </summary>
+ /// <param name="index">The zero-based index of the item to remove.</param>
public void RemoveAt(int index)
{
if (index < 0 || index >= count)
@@ -367,6 +466,14 @@
array[count] = default(T);
}
+ /// <summary>
+ /// Gets or sets the item at the specified index.
+ /// </summary>
+ /// <value>
+ /// The element at the specified index.
+ /// </value>
+ /// <param name="index">The zero-based index of the element to get or set.</param>
+ /// <returns>The item at the specified index.</returns>
public T this[int index]
{
get
diff --git a/csharp/src/Google.Protobuf/FieldCodec.cs b/csharp/src/Google.Protobuf/FieldCodec.cs
index 8546278..1076c2a 100644
--- a/csharp/src/Google.Protobuf/FieldCodec.cs
+++ b/csharp/src/Google.Protobuf/FieldCodec.cs
@@ -41,76 +41,152 @@
public static class FieldCodec
{
// TODO: Avoid the "dual hit" of lambda expressions: create open delegates instead. (At least test...)
+
+ /// <summary>
+ /// Retrieves a codec suitable for a string field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<string> ForString(uint tag)
{
return new FieldCodec<string>(input => input.ReadString(), (output, value) => output.WriteString(value), CodedOutputStream.ComputeStringSize, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a bytes field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<ByteString> ForBytes(uint tag)
{
return new FieldCodec<ByteString>(input => input.ReadBytes(), (output, value) => output.WriteBytes(value), CodedOutputStream.ComputeBytesSize, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a bool field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<bool> ForBool(uint tag)
{
return new FieldCodec<bool>(input => input.ReadBool(), (output, value) => output.WriteBool(value), CodedOutputStream.ComputeBoolSize, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an int32 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<int> ForInt32(uint tag)
{
return new FieldCodec<int>(input => input.ReadInt32(), (output, value) => output.WriteInt32(value), CodedOutputStream.ComputeInt32Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an sint32 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<int> ForSInt32(uint tag)
{
return new FieldCodec<int>(input => input.ReadSInt32(), (output, value) => output.WriteSInt32(value), CodedOutputStream.ComputeSInt32Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a fixed32 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<uint> ForFixed32(uint tag)
{
return new FieldCodec<uint>(input => input.ReadFixed32(), (output, value) => output.WriteFixed32(value), 4, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an sfixed32 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<int> ForSFixed32(uint tag)
{
return new FieldCodec<int>(input => input.ReadSFixed32(), (output, value) => output.WriteSFixed32(value), 4, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a uint32 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<uint> ForUInt32(uint tag)
{
return new FieldCodec<uint>(input => input.ReadUInt32(), (output, value) => output.WriteUInt32(value), CodedOutputStream.ComputeUInt32Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an int64 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<long> ForInt64(uint tag)
{
return new FieldCodec<long>(input => input.ReadInt64(), (output, value) => output.WriteInt64(value), CodedOutputStream.ComputeInt64Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an sint64 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<long> ForSInt64(uint tag)
{
return new FieldCodec<long>(input => input.ReadSInt64(), (output, value) => output.WriteSInt64(value), CodedOutputStream.ComputeSInt64Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a fixed64 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<ulong> ForFixed64(uint tag)
{
return new FieldCodec<ulong>(input => input.ReadFixed64(), (output, value) => output.WriteFixed64(value), 8, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for an sfixed64 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<long> ForSFixed64(uint tag)
{
return new FieldCodec<long>(input => input.ReadSFixed64(), (output, value) => output.WriteSFixed64(value), 8, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a uint64 field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<ulong> ForUInt64(uint tag)
{
return new FieldCodec<ulong>(input => input.ReadUInt64(), (output, value) => output.WriteUInt64(value), CodedOutputStream.ComputeUInt64Size, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a float field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<float> ForFloat(uint tag)
{
return new FieldCodec<float>(input => input.ReadFloat(), (output, value) => output.WriteFloat(value), CodedOutputStream.ComputeFloatSize, tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a double field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<double> ForDouble(uint tag)
{
return new FieldCodec<double>(input => input.ReadDouble(), (output, value) => output.WriteDouble(value), CodedOutputStream.ComputeDoubleSize, tag);
@@ -118,6 +194,14 @@
// Enums are tricky. We can probably use expression trees to build these delegates automatically,
// but it's easy to generate the code for it.
+
+ /// <summary>
+ /// Retrieves a codec suitable for an enum field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <param name="toInt32">A conversion function from <see cref="Int32"/> to the enum type.</param>
+ /// <param name="fromInt32">A conversion function from the enum type to <see cref="Int32"/>.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<T> ForEnum<T>(uint tag, Func<T, int> toInt32, Func<int, T> fromInt32)
{
return new FieldCodec<T>(input => fromInt32(
@@ -126,6 +210,12 @@
value => CodedOutputStream.ComputeEnumSize(toInt32(value)), tag);
}
+ /// <summary>
+ /// Retrieves a codec suitable for a message field with the given tag.
+ /// </summary>
+ /// <param name="tag">The tag.</param>
+ /// <param name="parser">A parser to use for the message type.</param>
+ /// <returns>A codec for the given tag.</returns>
public static FieldCodec<T> ForMessage<T>(uint tag, MessageParser<T> parser) where T : IMessage<T>
{
return new FieldCodec<T>(input => { T message = parser.CreateTemplate(); input.ReadMessage(message); return message; },
@@ -344,8 +434,20 @@
/// </summary>
internal int FixedSize { get { return fixedSize; } }
+ /// <summary>
+ /// Gets the tag of the codec.
+ /// </summary>
+ /// <value>
+ /// The tag of the codec.
+ /// </value>
public uint Tag { get { return tag; } }
+ /// <summary>
+ /// Gets the default value of the codec's type.
+ /// </summary>
+ /// <value>
+ /// The default value of the codec's type.
+ /// </value>
public T DefaultValue { get { return defaultValue; } }
/// <summary>
@@ -360,6 +462,11 @@
}
}
+ /// <summary>
+ /// Reads a value of the codec type from the given <see cref="CodedInputStream"/>.
+ /// </summary>
+ /// <param name="input">The input stream to read from.</param>
+ /// <returns>The value read from the stream.</returns>
public T Read(CodedInputStream input)
{
return reader(input);
diff --git a/csharp/src/Google.Protobuf/Google.Protobuf.csproj b/csharp/src/Google.Protobuf/Google.Protobuf.csproj
index 8a19067..033edfb 100644
--- a/csharp/src/Google.Protobuf/Google.Protobuf.csproj
+++ b/csharp/src/Google.Protobuf/Google.Protobuf.csproj
@@ -24,12 +24,14 @@
<OutputPath>bin\Debug</OutputPath>
<IntermediateOutputPath>obj\Debug\</IntermediateOutputPath>
<DocumentationFile>bin\Debug\Google.Protobuf.xml</DocumentationFile>
- <NoWarn>1591, 1570, 1571, 1572, 1573, 1574</NoWarn>
+ <NoWarn>
+ </NoWarn>
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<NoStdLib>true</NoStdLib>
<GenerateSerializationAssemblies>Off</GenerateSerializationAssemblies>
+ <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
@@ -37,12 +39,14 @@
<OutputPath>bin\Release</OutputPath>
<IntermediateOutputPath>obj\Release\</IntermediateOutputPath>
<DocumentationFile>$(OutputPath)\$(AssemblyName).xml</DocumentationFile>
- <NoWarn>1591, 1570, 1571, 1572, 1573, 1574</NoWarn>
+ <NoWarn>
+ </NoWarn>
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
<NoStdLib>true</NoStdLib>
<GenerateSerializationAssemblies>Off</GenerateSerializationAssemblies>
+ <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'ReleaseSigned|AnyCPU' ">
<DebugType>pdbonly</DebugType>
@@ -50,7 +54,8 @@
<OutputPath>bin\ReleaseSigned</OutputPath>
<IntermediateOutputPath>obj\ReleaseSigned\</IntermediateOutputPath>
<DocumentationFile>$(OutputPath)\$(AssemblyName).xml</DocumentationFile>
- <NoWarn>1591, 1570, 1571, 1572, 1573, 1574</NoWarn>
+ <NoWarn>
+ </NoWarn>
<DefineConstants>TRACE;SIGNED</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
@@ -58,6 +63,7 @@
<GenerateSerializationAssemblies>Off</GenerateSerializationAssemblies>
<SignAssembly>True</SignAssembly>
<AssemblyOriginatorKeyFile>C:\keys\Google.Protobuf.snk</AssemblyOriginatorKeyFile>
+ <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>
<ItemGroup>
<Reference Include="mscorlib" />
diff --git a/csharp/src/Google.Protobuf/IMessage.cs b/csharp/src/Google.Protobuf/IMessage.cs
index 60c6f8c..147c83c 100644
--- a/csharp/src/Google.Protobuf/IMessage.cs
+++ b/csharp/src/Google.Protobuf/IMessage.cs
@@ -91,8 +91,9 @@
/// <summary>
/// Generic interface for a deeply cloneable type.
- /// <summary>
+ /// </summary>
/// <remarks>
+ /// <para>
/// All generated messages implement this interface, but so do some non-message types.
/// Additionally, due to the type constraint on <c>T</c> in <see cref="IMessage{T}"/>,
/// it is simpler to keep this as a separate interface.
diff --git a/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs b/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs
index 4f89347..bbba9b3 100644
--- a/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs
+++ b/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs
@@ -45,7 +45,7 @@
{
}
- public static InvalidProtocolBufferException TruncatedMessage()
+ internal static InvalidProtocolBufferException TruncatedMessage()
{
return new InvalidProtocolBufferException(
"While parsing a protocol message, the input ended unexpectedly " +
@@ -61,12 +61,15 @@
"which claimed to have negative size.");
}
- public static InvalidProtocolBufferException MalformedVarint()
+ internal static InvalidProtocolBufferException MalformedVarint()
{
return new InvalidProtocolBufferException(
"CodedInputStream encountered a malformed varint.");
}
+ /// <summary>
+ /// Creates an exception for an error condition of an invalid tag being encountered.
+ /// </summary>
public static InvalidProtocolBufferException InvalidTag()
{
return new InvalidProtocolBufferException(
diff --git a/csharp/src/Google.Protobuf/JsonFormatter.cs b/csharp/src/Google.Protobuf/JsonFormatter.cs
index 999e106..edc4718 100644
--- a/csharp/src/Google.Protobuf/JsonFormatter.cs
+++ b/csharp/src/Google.Protobuf/JsonFormatter.cs
@@ -114,11 +114,20 @@
private readonly Settings settings;
+ /// <summary>
+ /// Creates a new formatted with the given settings.
+ /// </summary>
+ /// <param name="settings">The settings.</param>
public JsonFormatter(Settings settings)
{
this.settings = settings;
}
+ /// <summary>
+ /// Formats the specified message as JSON.
+ /// </summary>
+ /// <param name="message">The message to format.</param>
+ /// <returns>The formatted message.</returns>
public string Format(IMessage message)
{
Preconditions.CheckNotNull(message, "message");
@@ -768,6 +777,10 @@
/// </summary>
public bool FormatDefaultValues { get { return formatDefaultValues; } }
+ /// <summary>
+ /// Creates a new <see cref="Settings"/> object with the specified formatting of default values.
+ /// </summary>
+ /// <param name="formatDefaultValues"><c>true</c> if default values (0, empty strings etc) should be formatted; <c>false</c> otherwise.</param>
public Settings(bool formatDefaultValues)
{
this.formatDefaultValues = formatDefaultValues;
diff --git a/csharp/src/Google.Protobuf/MessageExtensions.cs b/csharp/src/Google.Protobuf/MessageExtensions.cs
index 6e7d47b..ee78dc8 100644
--- a/csharp/src/Google.Protobuf/MessageExtensions.cs
+++ b/csharp/src/Google.Protobuf/MessageExtensions.cs
@@ -39,6 +39,11 @@
/// </summary>
public static class MessageExtensions
{
+ /// <summary>
+ /// Merges data from the given byte array into an existing message.
+ /// </summary>
+ /// <param name="message">The message to merge the data into.</param>
+ /// <param name="data">The data to merge, which must be protobuf-encoded binary data.</param>
public static void MergeFrom(this IMessage message, byte[] data)
{
Preconditions.CheckNotNull(message, "message");
@@ -48,6 +53,11 @@
input.CheckLastTagWas(0);
}
+ /// <summary>
+ /// Merges data from the given byte string into an existing message.
+ /// </summary>
+ /// <param name="message">The message to merge the data into.</param>
+ /// <param name="data">The data to merge, which must be protobuf-encoded binary data.</param>
public static void MergeFrom(this IMessage message, ByteString data)
{
Preconditions.CheckNotNull(message, "message");
@@ -57,6 +67,11 @@
input.CheckLastTagWas(0);
}
+ /// <summary>
+ /// Merges data from the given stream into an existing message.
+ /// </summary>
+ /// <param name="message">The message to merge the data into.</param>
+ /// <param name="input">Stream containing the data to merge, which must be protobuf-encoded binary data.</param>
public static void MergeFrom(this IMessage message, Stream input)
{
Preconditions.CheckNotNull(message, "message");
@@ -66,6 +81,15 @@
codedInput.CheckLastTagWas(0);
}
+ /// <summary>
+ /// Merges length-delimited data from the given stream into an existing message.
+ /// </summary>
+ /// <remarks>
+ /// The stream is expected to contain a length and then the data. Only the amount of data
+ /// specified by the length will be consumed.
+ /// </remarks>
+ /// <param name="message">The message to merge the data into.</param>
+ /// <param name="input">Stream containing the data to merge, which must be protobuf-encoded binary data.</param>
public static void MergeDelimitedFrom(this IMessage message, Stream input)
{
Preconditions.CheckNotNull(message, "message");
@@ -75,6 +99,11 @@
message.MergeFrom(limitedStream);
}
+ /// <summary>
+ /// Converts the given message into a byte array in protobuf encoding.
+ /// </summary>
+ /// <param name="message">The message to convert.</param>
+ /// <returns>The message data as a byte array.</returns>
public static byte[] ToByteArray(this IMessage message)
{
Preconditions.CheckNotNull(message, "message");
@@ -85,6 +114,11 @@
return result;
}
+ /// <summary>
+ /// Writes the given message data to the given stream in protobuf encoding.
+ /// </summary>
+ /// <param name="message">The message to write to the stream.</param>
+ /// <param name="output">The stream to write to.</param>
public static void WriteTo(this IMessage message, Stream output)
{
Preconditions.CheckNotNull(message, "message");
@@ -94,6 +128,11 @@
codedOutput.Flush();
}
+ /// <summary>
+ /// Writes the length and then data of the given message to a stream.
+ /// </summary>
+ /// <param name="message">The message to write.</param>
+ /// <param name="output">The output stream to write to.</param>
public static void WriteDelimitedTo(this IMessage message, Stream output)
{
Preconditions.CheckNotNull(message, "message");
@@ -104,6 +143,11 @@
codedOutput.Flush();
}
+ /// <summary>
+ /// Converts the given message into a byte string in protobuf encoding.
+ /// </summary>
+ /// <param name="message">The message to convert.</param>
+ /// <returns>The message data as a byte string.</returns>
public static ByteString ToByteString(this IMessage message)
{
Preconditions.CheckNotNull(message, "message");
diff --git a/csharp/src/Google.Protobuf/MessageParser.cs b/csharp/src/Google.Protobuf/MessageParser.cs
index bfa63ae..6a6f101 100644
--- a/csharp/src/Google.Protobuf/MessageParser.cs
+++ b/csharp/src/Google.Protobuf/MessageParser.cs
@@ -90,6 +90,11 @@
return message;
}
+ /// <summary>
+ /// Parses a message from the given byte string.
+ /// </summary>
+ /// <param name="data">The data to parse.</param>
+ /// <returns>The parsed message.</returns>
public T ParseFrom(ByteString data)
{
Preconditions.CheckNotNull(data, "data");
@@ -98,6 +103,11 @@
return message;
}
+ /// <summary>
+ /// Parses a message from the given stream.
+ /// </summary>
+ /// <param name="input">The stream to parse.</param>
+ /// <returns>The parsed message.</returns>
public T ParseFrom(Stream input)
{
T message = factory();
@@ -105,6 +115,15 @@
return message;
}
+ /// <summary>
+ /// Parses a length-delimited message from the given stream.
+ /// </summary>
+ /// <remarks>
+ /// The stream is expected to contain a length and then the data. Only the amount of data
+ /// specified by the length will be consumed.
+ /// </remarks>
+ /// <param name="input">The stream to parse.</param>
+ /// <returns>The parsed message.</returns>
public T ParseDelimitedFrom(Stream input)
{
T message = factory();
@@ -112,6 +131,11 @@
return message;
}
+ /// <summary>
+ /// Parses a message from the given coded input stream.
+ /// </summary>
+ /// <param name="input">The stream to parse.</param>
+ /// <returns>The parsed message.</returns>
public T ParseFrom(CodedInputStream input)
{
T message = factory();
diff --git a/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs b/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs
index 0300cd5..194041a 100644
--- a/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs
+++ b/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs
@@ -61,6 +61,9 @@
get { return index; }
}
+ /// <summary>
+ /// Returns the name of the entity (field, message etc) being described.
+ /// </summary>
public abstract string Name { get; }
/// <summary>
diff --git a/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs
index 29833c4..b212ce9 100644
--- a/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs
@@ -51,11 +51,20 @@
}
internal EnumValueDescriptorProto Proto { get { return proto; } }
-
+
+ /// <summary>
+ /// Returns the name of the enum value described by this object.
+ /// </summary>
public override string Name { get { return proto.Name; } }
+ /// <summary>
+ /// Returns the number associated with this enum value.
+ /// </summary>
public int Number { get { return Proto.Number; } }
+ /// <summary>
+ /// Returns the enum descriptor that this value is part of.
+ /// </summary>
public EnumDescriptor EnumDescriptor { get { return enumDescriptor; } }
}
}
\ No newline at end of file
diff --git a/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs
index 60f2bb8..bb8e9bb 100644
--- a/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs
@@ -93,6 +93,15 @@
internal FieldDescriptorProto Proto { get { return proto; } }
+ /// <summary>
+ /// Returns the accessor for this field, or <c>null</c> if this descriptor does
+ /// not support reflective access.
+ /// </summary>
+ /// <remarks>
+ /// While a <see cref="FieldDescriptor"/> describes the field, it does not provide
+ /// any way of obtaining or changing the value of the field within a specific message;
+ /// that is the responsibility of the accessor.
+ /// </remarks>
public IFieldAccessor Accessor { get { return accessor; } }
/// <summary>
@@ -141,43 +150,61 @@
default:
throw new ArgumentException("Invalid type specified");
}
- }
+ }
+ /// <summary>
+ /// Returns <c>true</c> if this field is a repeated field; <c>false</c> otherwise.
+ /// </summary>
public bool IsRepeated
{
get { return Proto.Label == FieldDescriptorProto.Types.Label.LABEL_REPEATED; }
}
+ /// <summary>
+ /// Returns <c>true</c> if this field is a map field; <c>false</c> otherwise.
+ /// </summary>
public bool IsMap
{
get { return fieldType == FieldType.Message && messageType.Proto.Options != null && messageType.Proto.Options.MapEntry; }
}
+ // TODO(jonskeet): Check whether this is correct with proto3, where we default to packed...
+
+ /// <summary>
+ /// Returns <c>true</c> if this field is a packed, repeated field; <c>false</c> otherwise.
+ /// </summary>
public bool IsPacked
{
get { return Proto.Options != null && Proto.Options.Packed; }
}
/// <summary>
- /// Get the field's containing type. For extensions, this is the type being
- /// extended, not the location where the extension was defined. See
- /// <see cref="ExtensionScope" />.
+ /// Get the field's containing message type.
/// </summary>
public MessageDescriptor ContainingType
{
get { return containingType; }
}
+ /// <summary>
+ /// Returns the oneof containing this field, or <c>null</c> if it is not part of a oneof.
+ /// </summary>
public OneofDescriptor ContainingOneof
{
get { return containingOneof; }
- }
+ }
+ /// <summary>
+ /// Returns the type of the field.
+ /// </summary>
public FieldType FieldType
{
get { return fieldType; }
}
+ /// <summary>
+ /// Returns the field number declared in the proto file.
+ /// </summary>
public int FieldNumber
{
get { return Proto.Number; }
diff --git a/csharp/src/Google.Protobuf/Reflection/FieldType.cs b/csharp/src/Google.Protobuf/Reflection/FieldType.cs
index 41fa702..1658e34 100644
--- a/csharp/src/Google.Protobuf/Reflection/FieldType.cs
+++ b/csharp/src/Google.Protobuf/Reflection/FieldType.cs
@@ -33,28 +33,81 @@
namespace Google.Protobuf.Reflection
{
/// <summary>
- /// Enumeration of all the possible field types. The odd formatting is to make it very clear
- /// which attribute applies to which value, while maintaining a compact format.
+ /// Enumeration of all the possible field types.
/// </summary>
public enum FieldType
{
+ /// <summary>
+ /// The <c>double</c> field type.
+ /// </summary>
Double,
+ /// <summary>
+ /// The <c>float</c> field type.
+ /// </summary>
Float,
+ /// <summary>
+ /// The <c>int64</c> field type.
+ /// </summary>
Int64,
+ /// <summary>
+ /// The <c>uint64</c> field type.
+ /// </summary>
UInt64,
+ /// <summary>
+ /// The <c>int32</c> field type.
+ /// </summary>
Int32,
+ /// <summary>
+ /// The <c>fixed64</c> field type.
+ /// </summary>
Fixed64,
+ /// <summary>
+ /// The <c>fixed32</c> field type.
+ /// </summary>
Fixed32,
+ /// <summary>
+ /// The <c>bool</c> field type.
+ /// </summary>
Bool,
+ /// <summary>
+ /// The <c>string</c> field type.
+ /// </summary>
String,
+ /// <summary>
+ /// The field type used for groups (not supported in this implementation).
+ /// </summary>
Group,
+ /// <summary>
+ /// The field type used for message fields.
+ /// </summary>
Message,
+ /// <summary>
+ /// The <c>bytes</c> field type.
+ /// </summary>
Bytes,
+ /// <summary>
+ /// The <c>uint32</c> field type.
+ /// </summary>
UInt32,
+ /// <summary>
+ /// The <c>sfixed32</c> field type.
+ /// </summary>
SFixed32,
+ /// <summary>
+ /// The <c>sfixed64</c> field type.
+ /// </summary>
SFixed64,
+ /// <summary>
+ /// The <c>sint32</c> field type.
+ /// </summary>
SInt32,
+ /// <summary>
+ /// The <c>sint64</c> field type.
+ /// </summary>
SInt64,
+ /// <summary>
+ /// The field type used for enum fields.
+ /// </summary>
Enum
}
}
\ No newline at end of file
diff --git a/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs
index c17c4cc..7292770 100644
--- a/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs
@@ -51,18 +51,7 @@
private readonly IList<FileDescriptor> dependencies;
private readonly IList<FileDescriptor> publicDependencies;
private readonly DescriptorPool pool;
-
- public enum ProtoSyntax
- {
- Proto2,
- Proto3
- }
-
- public ProtoSyntax Syntax
- {
- get { return proto.Syntax == "proto3" ? ProtoSyntax.Proto3 : ProtoSyntax.Proto2; }
- }
-
+
private FileDescriptor(ByteString descriptorData, FileDescriptorProto proto, FileDescriptor[] dependencies, DescriptorPool pool, bool allowUnknownDependencies, GeneratedCodeInfo generatedCodeInfo)
{
this.descriptorData = descriptorData;
@@ -368,7 +357,13 @@
throw new ArgumentException("Invalid embedded descriptor for \"" + proto.Name + "\".", e);
}
}
-
+
+ /// <summary>
+ /// Returns a <see cref="System.String" /> that represents this instance.
+ /// </summary>
+ /// <returns>
+ /// A <see cref="System.String" /> that represents this instance.
+ /// </returns>
public override string ToString()
{
return "FileDescriptor for " + proto.Name;
diff --git a/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs
index 6506db1..318d58c 100644
--- a/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs
@@ -37,8 +37,19 @@
/// </summary>
public interface IDescriptor
{
+ /// <summary>
+ /// Returns the name of the entity (message, field etc) being described.
+ /// </summary>
string Name { get; }
+
+ /// <summary>
+ /// Returns the fully-qualified name of the entity being described.
+ /// </summary>
string FullName { get; }
+
+ /// <summary>
+ /// Returns the descriptor for the .proto file that this entity is part of.
+ /// </summary>
FileDescriptor File { get; }
}
}
\ No newline at end of file
diff --git a/csharp/src/Google.Protobuf/Reflection/IFieldAccessor.cs b/csharp/src/Google.Protobuf/Reflection/IFieldAccessor.cs
index 3f4f05f..f97d73e 100644
--- a/csharp/src/Google.Protobuf/Reflection/IFieldAccessor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/IFieldAccessor.cs
@@ -30,6 +30,9 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
+using System;
+using System.Collections;
+
namespace Google.Protobuf.Reflection
{
/// <summary>
@@ -64,7 +67,7 @@
/// Repeated fields are mutated by fetching the value and manipulating it as a list.
/// Map fields are mutated by fetching the value and manipulating it as a dictionary.
/// </remarks>
- /// <exception cref="InvalidOperationException">The field is not a "simple" field, or the message is frozen.</exception>
+ /// <exception cref="InvalidOperationException">The field is not a "simple" field.</exception>
void SetValue(object message, object value);
}
}
\ No newline at end of file
diff --git a/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs
index 0b562de..82901f1 100644
--- a/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/MessageDescriptor.cs
@@ -30,7 +30,6 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
-using Google.Protobuf.Collections;
using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
@@ -163,6 +162,9 @@
get { return enumTypes; }
}
+ /// <value>
+ /// An unmodifiable list of the "oneof" field collections in this message type.
+ /// </value>
public IList<OneofDescriptor> Oneofs
{
get { return oneofs; }
@@ -276,7 +278,7 @@
/// <summary>
/// Retrieves the descriptor for the field with the given name.
/// </summary>
- /// <param name="number">Number of the field to retrieve the descriptor for</param>
+ /// <param name="name">Name of the field to retrieve the descriptor for</param>
/// <returns>The descriptor for the given field</returns>
/// <exception cref="KeyNotFoundException">The message descriptor does not contain a field
/// with the given name</exception>
diff --git a/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs b/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs
index 8631a1c..ff51291 100644
--- a/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs
@@ -58,6 +58,12 @@
clearDelegate = ReflectionUtil.CreateActionObject(clearMethod);
}
+ /// <summary>
+ /// Gets the descriptor for this oneof.
+ /// </summary>
+ /// <value>
+ /// The descriptor of the oneof.
+ /// </value>
public OneofDescriptor Descriptor { get { return descriptor; } }
/// <summary>
diff --git a/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs
index 8571a5e..d51ee52 100644
--- a/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs
+++ b/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs
@@ -32,11 +32,14 @@
using System.Collections.Generic;
using System.Collections.ObjectModel;
-using System.Linq;
using Google.Protobuf.Compatibility;
namespace Google.Protobuf.Reflection
{
+ /// <summary>
+ /// Describes a "oneof" field collection in a message type: a set of
+ /// fields of which at most one can be set in any particular message.
+ /// </summary>
public sealed class OneofDescriptor : DescriptorBase
{
private readonly OneofDescriptorProto proto;
@@ -59,13 +62,33 @@
/// </summary>
public override string Name { get { return proto.Name; } }
+ /// <summary>
+ /// Gets the message type containing this oneof.
+ /// </summary>
+ /// <value>
+ /// The message type containing this oneof.
+ /// </value>
public MessageDescriptor ContainingType
{
get { return containingType; }
}
+ /// <summary>
+ /// Gets the fields within this oneof, in declaration order.
+ /// </summary>
+ /// <value>
+ /// The fields within this oneof, in declaration order.
+ /// </value>
public IList<FieldDescriptor> Fields { get { return fields; } }
+ /// <summary>
+ /// Gets an accessor for reflective access to the values associated with the oneof
+ /// in a particular message.
+ /// </summary>
+ /// <value>
+ /// The accessor used for reflective access, or <c>null</c> if reflection is not
+ /// supported by this descriptor.
+ /// </value>
public OneofAccessor Accessor { get { return accessor; } }
internal void CrossLink()
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs b/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
index c69d1b2..18ebefd 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs
@@ -38,7 +38,13 @@
// providing a conversion to TimeSpan and convenience operators.
public partial class Duration
{
+ /// <summary>
+ /// The number of nanoseconds in a second.
+ /// </summary>
public const int NanosecondsPerSecond = 1000000000;
+ /// <summary>
+ /// The number of nanoseconds in a BCL tick (as used by <see cref="TimeSpan"/> and <see cref="DateTime"/>).
+ /// </summary>
public const int NanosecondsPerTick = 100;
/// <summary>
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
index a3806b5..dd485d3 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs
@@ -43,16 +43,35 @@
/// </summary>
public static class TimeExtensions
{
+ /// <summary>
+ /// Converts the given <see cref="DateTime"/> to a <see cref="Timestamp"/>.
+ /// </summary>
+ /// <param name="dateTime">The date and time to convert to a timestamp.</param>
+ /// <exception cref="ArgumentException">The <paramref name="dateTime"/> value has a <see cref="DateTime.Kind"/>other than <c>Utc</c>.</exception>
+ /// <returns>The converted timestamp.</returns>
public static Timestamp ToTimestamp(this DateTime dateTime)
{
return Timestamp.FromDateTime(dateTime);
}
+ /// <summary>
+ /// Converts the given <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>
+ /// </summary>
+ /// <remarks>The offset is taken into consideration when converting the value (so the same instant in time
+ /// is represented) but is not a separate part of the resulting value. In other words, there is no
+ /// roundtrip operation to retrieve the original <c>DateTimeOffset</c>.</remarks>
+ /// <param name="dateTimeOffset">The date and time (with UTC offset) to convert to a timestamp.</param>
+ /// <returns>The converted timestamp.</returns>
public static Timestamp ToTimestamp(this DateTimeOffset dateTimeOffset)
{
return Timestamp.FromDateTimeOffset(dateTimeOffset);
}
+ /// <summary>
+ /// Converts the given <see cref="TimeSpan"/> to a <see cref="Duration"/>.
+ /// </summary>
+ /// <param name="timeSpan">The time span to convert.</param>
+ /// <returns>The converted duration.</returns>
public static Duration ToDuration(this TimeSpan timeSpan)
{
return Duration.FromTimeSpan(timeSpan);
diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs b/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
index 1aa392c..6858435 100644
--- a/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
+++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs
@@ -136,9 +136,12 @@
}
/// <summary>
- /// Converts the specified <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>.
+ /// Converts the given <see cref="DateTimeOffset"/> to a <see cref="Timestamp"/>
/// </summary>
- /// <param name="dateTime"></param>
+ /// <remarks>The offset is taken into consideration when converting the value (so the same instant in time
+ /// is represented) but is not a separate part of the resulting value. In other words, there is no
+ /// roundtrip operation to retrieve the original <c>DateTimeOffset</c>.</remarks>
+ /// <param name="dateTimeOffset">The date and time (with UTC offset) to convert to a timestamp.</param>
/// <returns>The converted timestamp.</returns>
public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset)
{
diff --git a/csharp/src/Google.Protobuf/WireFormat.cs b/csharp/src/Google.Protobuf/WireFormat.cs
index c1712da..bbd7e4f 100644
--- a/csharp/src/Google.Protobuf/WireFormat.cs
+++ b/csharp/src/Google.Protobuf/WireFormat.cs
@@ -30,9 +30,6 @@
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#endregion
-using System;
-using Google.Protobuf.Reflection;
-
namespace Google.Protobuf
{
/// <summary>
@@ -59,13 +56,34 @@
#endregion
+ /// <summary>
+ /// Wire types within protobuf encoding.
+ /// </summary>
public enum WireType : uint
{
+ /// <summary>
+ /// Variable-length integer.
+ /// </summary>
Varint = 0,
+ /// <summary>
+ /// A fixed-length 64-bit value.
+ /// </summary>
Fixed64 = 1,
+ /// <summary>
+ /// A length-delimited value, i.e. a length followed by that many bytes of data.
+ /// </summary>
LengthDelimited = 2,
+ /// <summary>
+ /// A "start group" value - not supported by this implementation.
+ /// </summary>
StartGroup = 3,
+ /// <summary>
+ /// An "end group" value - not supported by this implementation.
+ /// </summary>
EndGroup = 4,
+ /// <summary>
+ /// A fixed-length 32-bit value.
+ /// </summary>
Fixed32 = 5
}
@@ -80,6 +98,11 @@
return (WireType) (tag & TagTypeMask);
}
+ /// <summary>
+ /// Determines whether the given tag is an end group tag.
+ /// </summary>
+ /// <param name="tag">The tag to check.</param>
+ /// <returns><c>true</c> if the given tag is an end group tag; <c>false</c> otherwise.</returns>
public static bool IsEndGroupTag(uint tag)
{
return (WireType) (tag & TagTypeMask) == WireType.EndGroup;
@@ -99,64 +122,6 @@
public static uint MakeTag(int fieldNumber, WireType wireType)
{
return (uint) (fieldNumber << TagTypeBits) | (uint) wireType;
- }
-
- public static uint MakeTag(FieldDescriptor field)
- {
- return MakeTag(field.FieldNumber, GetWireType(field));
- }
-
- /// <summary>
- /// Returns the wire type for the given field descriptor. This differs
- /// from GetWireType(FieldType) for packed repeated fields.
- /// </summary>
- internal static WireType GetWireType(FieldDescriptor descriptor)
- {
- return descriptor.IsPacked ? WireType.LengthDelimited : GetWireType(descriptor.FieldType);
- }
-
- /// <summary>
- /// Converts a field type to its wire type. Done with a switch for the sake
- /// of speed - this is significantly faster than a dictionary lookup.
- /// </summary>
- public static WireType GetWireType(FieldType fieldType)
- {
- switch (fieldType)
- {
- case FieldType.Double:
- return WireType.Fixed64;
- case FieldType.Float:
- return WireType.Fixed32;
- case FieldType.Int64:
- case FieldType.UInt64:
- case FieldType.Int32:
- return WireType.Varint;
- case FieldType.Fixed64:
- return WireType.Fixed64;
- case FieldType.Fixed32:
- return WireType.Fixed32;
- case FieldType.Bool:
- return WireType.Varint;
- case FieldType.String:
- return WireType.LengthDelimited;
- case FieldType.Group:
- return WireType.StartGroup;
- case FieldType.Message:
- case FieldType.Bytes:
- return WireType.LengthDelimited;
- case FieldType.UInt32:
- return WireType.Varint;
- case FieldType.SFixed32:
- return WireType.Fixed32;
- case FieldType.SFixed64:
- return WireType.Fixed64;
- case FieldType.SInt32:
- case FieldType.SInt64:
- case FieldType.Enum:
- return WireType.Varint;
- default:
- throw new ArgumentOutOfRangeException("fieldType", "No such field type");
- }
- }
+ }
}
}
\ No newline at end of file