From 811fc89f0eb036d95653f5fed4b0ffea292ce791 Mon Sep 17 00:00:00 2001 From: Jon Skeet Date: Tue, 4 Aug 2015 15:58:39 +0100 Subject: Document everything, and turn on errors if we fail to document anything in the future. --- csharp/src/Google.Protobuf/ByteString.cs | 74 ++++++++++- csharp/src/Google.Protobuf/CodedInputStream.cs | 2 +- csharp/src/Google.Protobuf/CodedOutputStream.cs | 7 + csharp/src/Google.Protobuf/Collections/MapField.cs | 141 ++++++++++++++++++++- .../Google.Protobuf/Collections/RepeatedField.cs | 111 +++++++++++++++- csharp/src/Google.Protobuf/FieldCodec.cs | 107 ++++++++++++++++ csharp/src/Google.Protobuf/Google.Protobuf.csproj | 12 +- csharp/src/Google.Protobuf/IMessage.cs | 3 +- .../InvalidProtocolBufferException.cs | 7 +- csharp/src/Google.Protobuf/JsonFormatter.cs | 13 ++ csharp/src/Google.Protobuf/MessageExtensions.cs | 44 +++++++ csharp/src/Google.Protobuf/MessageParser.cs | 24 ++++ .../Google.Protobuf/Reflection/DescriptorBase.cs | 3 + .../Reflection/EnumValueDescriptor.cs | 11 +- .../Google.Protobuf/Reflection/FieldDescriptor.cs | 37 +++++- csharp/src/Google.Protobuf/Reflection/FieldType.cs | 57 ++++++++- .../Google.Protobuf/Reflection/FileDescriptor.cs | 21 ++- .../src/Google.Protobuf/Reflection/IDescriptor.cs | 11 ++ .../Google.Protobuf/Reflection/IFieldAccessor.cs | 5 +- .../Reflection/MessageDescriptor.cs | 6 +- .../Google.Protobuf/Reflection/OneofAccessor.cs | 6 + .../Google.Protobuf/Reflection/OneofDescriptor.cs | 25 +++- .../WellKnownTypes/DurationPartial.cs | 6 + .../WellKnownTypes/TimeExtensions.cs | 19 +++ .../WellKnownTypes/TimestampPartial.cs | 7 +- csharp/src/Google.Protobuf/WireFormat.cs | 89 ++++--------- 26 files changed, 741 insertions(+), 107 deletions(-) (limited to 'csharp') diff --git a/csharp/src/Google.Protobuf/ByteString.cs b/csharp/src/Google.Protobuf/ByteString.cs index cf5468d2..2aa62483 100644 --- a/csharp/src/Google.Protobuf/ByteString.cs +++ b/csharp/src/Google.Protobuf/ByteString.cs @@ -105,23 +105,35 @@ namespace Google.Protobuf get { return bytes.Length; } } + /// + /// Returns true if this byte string is empty, false otherwise. + /// public bool IsEmpty { get { return Length == 0; } } + /// + /// Converts this into a byte array. + /// + /// The data is copied - changes to the returned array will not be reflected in this ByteString. + /// A byte array with the same data as this ByteString. public byte[] ToByteArray() { return (byte[]) bytes.Clone(); } + /// + /// Converts this into a standard base64 representation. + /// + /// A base64 representation of this ByteString. public string ToBase64() { return Convert.ToBase64String(bytes); } /// - /// Constructs a ByteString from the Base64 Encoded String. + /// Constructs a from the Base64 Encoded String. /// public static ByteString FromBase64(string bytes) { @@ -131,7 +143,7 @@ namespace Google.Protobuf } /// - /// Constructs a ByteString from the given array. The contents + /// Constructs a 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 ByteString.CopyFrom(0xaa, 0xbb, ...) form @@ -143,7 +155,7 @@ namespace Google.Protobuf } /// - /// Constructs a ByteString from a portion of a byte array. + /// Constructs a from a portion of a byte array. /// public static ByteString CopyFrom(byte[] bytes, int offset, int count) { @@ -153,7 +165,7 @@ namespace Google.Protobuf } /// - /// Creates a new ByteString by encoding the specified text with + /// Creates a new by encoding the specified text with /// the given encoding. /// public static ByteString CopyFrom(string text, Encoding encoding) @@ -162,7 +174,7 @@ namespace Google.Protobuf } /// - /// Creates a new ByteString by encoding the specified text in UTF-8. + /// Creates a new by encoding the specified text in UTF-8. /// public static ByteString CopyFromUtf8(string text) { @@ -177,21 +189,46 @@ namespace Google.Protobuf get { return bytes[index]; } } + /// + /// Converts this into a string by applying the given encoding. + /// + /// + /// This method should only be used to convert binary data which was the result of encoding + /// text with the given encoding. + /// + /// The encoding to use to decode the binary data into text. + /// The result of decoding the binary data with the given decoding. public string ToString(Encoding encoding) { return encoding.GetString(bytes, 0, bytes.Length); } + /// + /// Converts this into a string by applying the UTF-8 encoding. + /// + /// + /// This method should only be used to convert binary data which was the result of encoding + /// text with UTF-8. + /// + /// The result of decoding the binary data with the given decoding. public string ToStringUtf8() { return ToString(Encoding.UTF8); } + /// + /// Returns an iterator over the bytes in this . + /// + /// An iterator over the bytes in this object. public IEnumerator GetEnumerator() { return ((IEnumerable) bytes).GetEnumerator(); } + /// + /// Returns an iterator over the bytes in this . + /// + /// An iterator over the bytes in this object. IEnumerator IEnumerable.GetEnumerator() { return GetEnumerator(); @@ -206,6 +243,12 @@ namespace Google.Protobuf return new CodedInputStream(bytes); } + /// + /// Compares two byte strings for equality. + /// + /// The first byte string to compare. + /// The second byte string to compare. + /// true if the byte strings are equal; false otherwise. public static bool operator ==(ByteString lhs, ByteString rhs) { if (ReferenceEquals(lhs, rhs)) @@ -230,6 +273,12 @@ namespace Google.Protobuf return true; } + /// + /// Compares two byte strings for inequality. + /// + /// The first byte string to compare. + /// The second byte string to compare. + /// false if the byte strings are equal; true otherwise. public static bool operator !=(ByteString lhs, ByteString rhs) { return !(lhs == rhs); @@ -237,11 +286,21 @@ namespace Google.Protobuf // TODO(jonskeet): CopyTo if it turns out to be required + /// + /// Compares this byte string with another object. + /// + /// The object to compare this with. + /// true if refers to an equal ; false otherwise. public override bool Equals(object obj) { return this == (obj as ByteString); } + /// + /// Returns a hash code for this object. Two equal byte strings + /// will return the same hash code. + /// + /// A hash code for this object. public override int GetHashCode() { int ret = 23; @@ -252,6 +311,11 @@ namespace Google.Protobuf return ret; } + /// + /// Compares this byte string with another. + /// + /// The to compare this with. + /// true if refers to an equal byte string; false otherwise. 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 f2e1d661..a1abfcb0 100644 --- a/csharp/src/Google.Protobuf/CodedInputStream.cs +++ b/csharp/src/Google.Protobuf/CodedInputStream.cs @@ -66,7 +66,7 @@ namespace Google.Protobuf internal const int DefaultRecursionLimit = 64; internal const int DefaultSizeLimit = 64 << 20; // 64MB - public const int BufferSize = 4096; + internal const int BufferSize = 4096; /// /// 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 b084c14f..08ea7005 100644 --- a/csharp/src/Google.Protobuf/CodedOutputStream.cs +++ b/csharp/src/Google.Protobuf/CodedOutputStream.cs @@ -297,6 +297,10 @@ namespace Google.Protobuf WriteInt32(value); } + /// + /// Writes an sfixed32 value, without a tag, to the stream. + /// + /// The value to write. public void WriteSFixed32(int value) { WriteRawLittleEndian32((uint) value); @@ -649,6 +653,9 @@ namespace Google.Protobuf } } + /// + /// Flushes any buffered data to the underlying stream (if there is one). + /// 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 fc94fd5c..fed3d062 100644 --- a/csharp/src/Google.Protobuf/Collections/MapField.cs +++ b/csharp/src/Google.Protobuf/Collections/MapField.cs @@ -42,14 +42,14 @@ namespace Google.Protobuf.Collections /// /// Representation of a map field in a Protocol Buffer message. /// + /// Key type in the map. Must be a type supported by Protocol Buffer map keys. + /// Value type in the map. Must be a type supported by Protocol Buffers. /// /// 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 . + /// For string keys, the equality comparison is provided by . /// - /// Key type in the map. Must be a type supported by Protocol Buffer map keys. - /// Value type in the map. Must be a type supported by Protocol Buffers. public sealed class MapField : IDeepCloneable>, IDictionary, IEquatable>, IDictionary { // TODO: Don't create the map/list until we have an entry. (Assume many maps will be empty.) @@ -81,6 +81,12 @@ namespace Google.Protobuf.Collections this.allowNullValues = allowNullValues; } + /// + /// Creates a deep clone of this object. + /// + /// + /// A deep clone of this object. + /// public MapField Clone() { var clone = new MapField(allowNullValues); @@ -100,6 +106,15 @@ namespace Google.Protobuf.Collections return clone; } + /// + /// Adds the specified key/value pair to the map. + /// + /// + /// This operation fails if the key already exists in the map. To replace an existing entry, use the indexer. + /// + /// The key to add + /// The value to add. + /// The given key already exists in map. public void Add(TKey key, TValue value) { // Validation of arguments happens in ContainsKey and the indexer @@ -110,12 +125,22 @@ namespace Google.Protobuf.Collections this[key] = value; } + /// + /// Determines whether the specified key is present in the map. + /// + /// The key to check. + /// true if the map contains the given key; false otherwise. public bool ContainsKey(TKey key) { Preconditions.CheckNotNullUnconstrained(key, "key"); return map.ContainsKey(key); } + /// + /// Removes the entry identified by the given key from the map. + /// + /// The key indicating the entry to remove from the map. + /// true if the map contained the given key before the entry was removed; false otherwise. public bool Remove(TKey key) { Preconditions.CheckNotNullUnconstrained(key, "key"); @@ -132,6 +157,14 @@ namespace Google.Protobuf.Collections } } + /// + /// Gets the value associated with the specified key. + /// + /// The key whose value to get. + /// 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 parameter. + /// This parameter is passed uninitialized. + /// true if the map contains an element with the specified key; otherwise, false. public bool TryGetValue(TKey key, out TValue value) { LinkedListNode> node; @@ -147,6 +180,13 @@ namespace Google.Protobuf.Collections } } + /// + /// Gets or sets the value associated with the specified key. + /// + /// The key of the value to get or set. + /// The property is retrieved and key does not exist in the collection. + /// The value associated with the specified key. If the specified key is not found, + /// a get operation throws a , and a set operation creates a new element with the specified key. public TValue this[TKey key] { get @@ -182,9 +222,21 @@ namespace Google.Protobuf.Collections } // TODO: Make these views? + + /// + /// Gets a collection containing the keys in the map. + /// public ICollection Keys { get { return list.Select(t => t.Key).ToList(); } } + + /// + /// Gets a collection containing the values in the map. + /// public ICollection Values { get { return list.Select(t => t.Value).ToList(); } } + /// + /// Adds the specified entries to the map. + /// + /// The entries to add to the map. public void Add(IDictionary entries) { Preconditions.CheckNotNull(entries, "entries"); @@ -194,27 +246,51 @@ namespace Google.Protobuf.Collections } } + /// + /// Returns an enumerator that iterates through the collection. + /// + /// + /// An enumerator that can be used to iterate through the collection. + /// public IEnumerator> GetEnumerator() { return list.GetEnumerator(); } + /// + /// Returns an enumerator that iterates through a collection. + /// + /// + /// An object that can be used to iterate through the collection. + /// IEnumerator IEnumerable.GetEnumerator() { return GetEnumerator(); } + /// + /// Adds the specified item to the map. + /// + /// The item to add to the map. void ICollection>.Add(KeyValuePair item) { Add(item.Key, item.Value); } + /// + /// Removes all items from the map. + /// public void Clear() { list.Clear(); map.Clear(); } + /// + /// Determines whether map contains an entry equivalent to the given key/value pair. + /// + /// The key/value pair to find. + /// bool ICollection>.Contains(KeyValuePair item) { TValue value; @@ -222,11 +298,22 @@ namespace Google.Protobuf.Collections && EqualityComparer.Default.Equals(item.Value, value); } + /// + /// Copies the key/value pairs in this map to an array. + /// + /// The array to copy the entries into. + /// The index of the array at which to start copying values. void ICollection>.CopyTo(KeyValuePair[] array, int arrayIndex) { list.CopyTo(array, arrayIndex); } + /// + /// Removes the specified key/value pair from the map. + /// + /// Both the key and the value must be found for the entry to be removed. + /// The key/value pair to remove. + /// true if the key/value pair was found and removed; false otherwise. bool ICollection>.Remove(KeyValuePair item) { if (item.Key == null) @@ -252,14 +339,34 @@ namespace Google.Protobuf.Collections /// public bool AllowsNullValues { get { return allowNullValues; } } + /// + /// Gets the number of elements contained in the map. + /// public int Count { get { return list.Count; } } + + /// + /// Gets a value indicating whether the map is read-only. + /// public bool IsReadOnly { get { return false; } } + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The to compare with this instance. + /// + /// true if the specified is equal to this instance; otherwise, false. + /// public override bool Equals(object other) { return Equals(other as MapField); } + /// + /// Returns a hash code for this instance. + /// + /// + /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table. + /// public override int GetHashCode() { var valueComparer = EqualityComparer.Default; @@ -271,6 +378,14 @@ namespace Google.Protobuf.Collections return hash; } + /// + /// Compares this map with another for equality. + /// + /// + /// The order of the key/value pairs in the maps is not deemed significant in this comparison. + /// + /// The map to compare this with. + /// true if refers to an equal map; false otherwise. public bool Equals(MapField other) { if (other == null) @@ -322,6 +437,12 @@ namespace Google.Protobuf.Collections } while (input.MaybeConsumeTag(codec.MapTag)); } + /// + /// Writes the contents of this map to the given coded output stream, using the specified codec + /// to encode each entry. + /// + /// The output stream to write to. + /// The codec to use for each entry. public void WriteTo(CodedOutputStream output, Codec codec) { var message = new Codec.MessageAdapter(codec); @@ -334,6 +455,11 @@ namespace Google.Protobuf.Collections } } + /// + /// Calculates the size of this map based on the given entry codec. + /// + /// The codec to use to encode each entry. + /// public int CalculateSize(Codec codec) { if (Count == 0) @@ -446,7 +572,7 @@ namespace Google.Protobuf.Collections } /// - /// 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. /// public sealed class Codec @@ -455,6 +581,13 @@ namespace Google.Protobuf.Collections private readonly FieldCodec valueCodec; private readonly uint mapTag; + /// + /// Creates a new entry codec based on a separate key codec and value codec, + /// and the tag to use for each map entry. + /// + /// The key codec. + /// The value codec. + /// The map tag to use to introduce each map entry. public Codec(FieldCodec keyCodec, FieldCodec 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 3ce19c81..c901864a 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 @@ namespace Google.Protobuf.Collections return clone; } + /// + /// Adds the entries from the given input stream, decoding them with the specified codec. + /// + /// The input stream to read from. + /// The codec to use in order to read each entry. public void AddEntriesFrom(CodedInputStream input, FieldCodec codec) { // TODO: Inline some of the Add code, so we can avoid checking the size on every @@ -112,6 +116,12 @@ namespace Google.Protobuf.Collections } } + /// + /// Calculates the size of this collection based on the given codec. + /// + /// The codec to use when encoding each field. + /// The number of bytes that would be written to a by , + /// using the same codec. public int CalculateSize(FieldCodec codec) { if (count == 0) @@ -157,6 +167,12 @@ namespace Google.Protobuf.Collections } } + /// + /// Writes the contents of this collection to the given , + /// encoding each value using the specified codec. + /// + /// The output stream to write to. + /// The codec to use when encoding each value. public void WriteTo(CodedOutputStream output, FieldCodec codec) { if (count == 0) @@ -200,6 +216,10 @@ namespace Google.Protobuf.Collections } } + /// + /// Adds the specified item to the collection. + /// + /// The item to add. public void Add(T item) { if (item == null) @@ -210,22 +230,40 @@ namespace Google.Protobuf.Collections array[count++] = item; } + /// + /// Removes all items from the collection. + /// public void Clear() { array = EmptyArray; count = 0; } + /// + /// Determines whether this collection contains the given item. + /// + /// The item to find. + /// true if this collection contains the given item; false otherwise. public bool Contains(T item) { return IndexOf(item) != -1; } + /// + /// Copies this collection to the given array. + /// + /// The array to copy to. + /// The first index of the array to copy to. public void CopyTo(T[] array, int arrayIndex) { Array.Copy(this.array, 0, array, arrayIndex, count); } + /// + /// Removes the specified item from the collection + /// + /// The item to remove. + /// true if the item was found and removed; false otherwise. public bool Remove(T item) { int index = IndexOf(item); @@ -239,10 +277,22 @@ namespace Google.Protobuf.Collections return true; } + /// + /// Gets the number of elements contained in the collection. + /// public int Count { get { return count; } } + /// + /// Gets a value indicating whether the collection is read-only. + /// public bool IsReadOnly { get { return false; } } + // TODO: Remove this overload and just handle it in the one below, at execution time? + + /// + /// Adds all of the specified values into this collection. + /// + /// The values to add to this collection. public void Add(RepeatedField values) { if (values == null) @@ -255,6 +305,10 @@ namespace Google.Protobuf.Collections count += values.count; } + /// + /// Adds all of the specified values into this collection. + /// + /// The values to add to this collection. public void Add(IEnumerable values) { if (values == null) @@ -268,6 +322,12 @@ namespace Google.Protobuf.Collections } } + /// + /// Returns an enumerator that iterates through the collection. + /// + /// + /// An enumerator that can be used to iterate through the collection. + /// public IEnumerator GetEnumerator() { for (int i = 0; i < count; i++) @@ -276,16 +336,35 @@ namespace Google.Protobuf.Collections } } + /// + /// Determines whether the specified , is equal to this instance. + /// + /// The to compare with this instance. + /// + /// true if the specified is equal to this instance; otherwise, false. + /// public override bool Equals(object obj) { return Equals(obj as RepeatedField); } + /// + /// Returns an enumerator that iterates through a collection. + /// + /// + /// An object that can be used to iterate through the collection. + /// IEnumerator IEnumerable.GetEnumerator() { return GetEnumerator(); - } + } + /// + /// Returns a hash code for this instance. + /// + /// + /// A hash code for this instance, suitable for use in hashing algorithms and data structures like a hash table. + /// public override int GetHashCode() { int hash = 0; @@ -296,6 +375,11 @@ namespace Google.Protobuf.Collections return hash; } + /// + /// Compares this repeated field with another for equality. + /// + /// The repeated field to compare this with. + /// true if refers to an equal repeated field; false otherwise. public bool Equals(RepeatedField other) { if (ReferenceEquals(other, null)) @@ -322,6 +406,12 @@ namespace Google.Protobuf.Collections return true; } + /// + /// Returns the index of the given item within the collection, or -1 if the item is not + /// present. + /// + /// The item to find in the collection. + /// The zero-based index of the item, or -1 if it is not found. public int IndexOf(T item) { if (item == null) @@ -340,6 +430,11 @@ namespace Google.Protobuf.Collections return -1; } + /// + /// Inserts the given item at the specified index. + /// + /// The index at which to insert the item. + /// The item to insert. public void Insert(int index, T item) { if (item == null) @@ -356,6 +451,10 @@ namespace Google.Protobuf.Collections count++; } + /// + /// Removes the item at the given index. + /// + /// The zero-based index of the item to remove. public void RemoveAt(int index) { if (index < 0 || index >= count) @@ -367,6 +466,14 @@ namespace Google.Protobuf.Collections array[count] = default(T); } + /// + /// Gets or sets the item at the specified index. + /// + /// + /// The element at the specified index. + /// + /// The zero-based index of the element to get or set. + /// The item at the specified index. public T this[int index] { get diff --git a/csharp/src/Google.Protobuf/FieldCodec.cs b/csharp/src/Google.Protobuf/FieldCodec.cs index 85462787..1076c2a9 100644 --- a/csharp/src/Google.Protobuf/FieldCodec.cs +++ b/csharp/src/Google.Protobuf/FieldCodec.cs @@ -41,76 +41,152 @@ namespace Google.Protobuf public static class FieldCodec { // TODO: Avoid the "dual hit" of lambda expressions: create open delegates instead. (At least test...) + + /// + /// Retrieves a codec suitable for a string field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForString(uint tag) { return new FieldCodec(input => input.ReadString(), (output, value) => output.WriteString(value), CodedOutputStream.ComputeStringSize, tag); } + /// + /// Retrieves a codec suitable for a bytes field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForBytes(uint tag) { return new FieldCodec(input => input.ReadBytes(), (output, value) => output.WriteBytes(value), CodedOutputStream.ComputeBytesSize, tag); } + /// + /// Retrieves a codec suitable for a bool field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForBool(uint tag) { return new FieldCodec(input => input.ReadBool(), (output, value) => output.WriteBool(value), CodedOutputStream.ComputeBoolSize, tag); } + /// + /// Retrieves a codec suitable for an int32 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForInt32(uint tag) { return new FieldCodec(input => input.ReadInt32(), (output, value) => output.WriteInt32(value), CodedOutputStream.ComputeInt32Size, tag); } + /// + /// Retrieves a codec suitable for an sint32 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForSInt32(uint tag) { return new FieldCodec(input => input.ReadSInt32(), (output, value) => output.WriteSInt32(value), CodedOutputStream.ComputeSInt32Size, tag); } + /// + /// Retrieves a codec suitable for a fixed32 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForFixed32(uint tag) { return new FieldCodec(input => input.ReadFixed32(), (output, value) => output.WriteFixed32(value), 4, tag); } + /// + /// Retrieves a codec suitable for an sfixed32 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForSFixed32(uint tag) { return new FieldCodec(input => input.ReadSFixed32(), (output, value) => output.WriteSFixed32(value), 4, tag); } + /// + /// Retrieves a codec suitable for a uint32 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForUInt32(uint tag) { return new FieldCodec(input => input.ReadUInt32(), (output, value) => output.WriteUInt32(value), CodedOutputStream.ComputeUInt32Size, tag); } + /// + /// Retrieves a codec suitable for an int64 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForInt64(uint tag) { return new FieldCodec(input => input.ReadInt64(), (output, value) => output.WriteInt64(value), CodedOutputStream.ComputeInt64Size, tag); } + /// + /// Retrieves a codec suitable for an sint64 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForSInt64(uint tag) { return new FieldCodec(input => input.ReadSInt64(), (output, value) => output.WriteSInt64(value), CodedOutputStream.ComputeSInt64Size, tag); } + /// + /// Retrieves a codec suitable for a fixed64 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForFixed64(uint tag) { return new FieldCodec(input => input.ReadFixed64(), (output, value) => output.WriteFixed64(value), 8, tag); } + /// + /// Retrieves a codec suitable for an sfixed64 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForSFixed64(uint tag) { return new FieldCodec(input => input.ReadSFixed64(), (output, value) => output.WriteSFixed64(value), 8, tag); } + /// + /// Retrieves a codec suitable for a uint64 field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForUInt64(uint tag) { return new FieldCodec(input => input.ReadUInt64(), (output, value) => output.WriteUInt64(value), CodedOutputStream.ComputeUInt64Size, tag); } + /// + /// Retrieves a codec suitable for a float field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForFloat(uint tag) { return new FieldCodec(input => input.ReadFloat(), (output, value) => output.WriteFloat(value), CodedOutputStream.ComputeFloatSize, tag); } + /// + /// Retrieves a codec suitable for a double field with the given tag. + /// + /// The tag. + /// A codec for the given tag. public static FieldCodec ForDouble(uint tag) { return new FieldCodec(input => input.ReadDouble(), (output, value) => output.WriteDouble(value), CodedOutputStream.ComputeDoubleSize, tag); @@ -118,6 +194,14 @@ namespace Google.Protobuf // Enums are tricky. We can probably use expression trees to build these delegates automatically, // but it's easy to generate the code for it. + + /// + /// Retrieves a codec suitable for an enum field with the given tag. + /// + /// The tag. + /// A conversion function from to the enum type. + /// A conversion function from the enum type to . + /// A codec for the given tag. public static FieldCodec ForEnum(uint tag, Func toInt32, Func fromInt32) { return new FieldCodec(input => fromInt32( @@ -126,6 +210,12 @@ namespace Google.Protobuf value => CodedOutputStream.ComputeEnumSize(toInt32(value)), tag); } + /// + /// Retrieves a codec suitable for a message field with the given tag. + /// + /// The tag. + /// A parser to use for the message type. + /// A codec for the given tag. public static FieldCodec ForMessage(uint tag, MessageParser parser) where T : IMessage { return new FieldCodec(input => { T message = parser.CreateTemplate(); input.ReadMessage(message); return message; }, @@ -344,8 +434,20 @@ namespace Google.Protobuf /// internal int FixedSize { get { return fixedSize; } } + /// + /// Gets the tag of the codec. + /// + /// + /// The tag of the codec. + /// public uint Tag { get { return tag; } } + /// + /// Gets the default value of the codec's type. + /// + /// + /// The default value of the codec's type. + /// public T DefaultValue { get { return defaultValue; } } /// @@ -360,6 +462,11 @@ namespace Google.Protobuf } } + /// + /// Reads a value of the codec type from the given . + /// + /// The input stream to read from. + /// The value read from the stream. 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 8a19067a..033edfbb 100644 --- a/csharp/src/Google.Protobuf/Google.Protobuf.csproj +++ b/csharp/src/Google.Protobuf/Google.Protobuf.csproj @@ -24,12 +24,14 @@ bin\Debug obj\Debug\ bin\Debug\Google.Protobuf.xml - 1591, 1570, 1571, 1572, 1573, 1574 + + DEBUG;TRACE prompt 4 true Off + true pdbonly @@ -37,12 +39,14 @@ bin\Release obj\Release\ $(OutputPath)\$(AssemblyName).xml - 1591, 1570, 1571, 1572, 1573, 1574 + + TRACE prompt 4 true Off + true pdbonly @@ -50,7 +54,8 @@ bin\ReleaseSigned obj\ReleaseSigned\ $(OutputPath)\$(AssemblyName).xml - 1591, 1570, 1571, 1572, 1573, 1574 + + TRACE;SIGNED prompt 4 @@ -58,6 +63,7 @@ Off True C:\keys\Google.Protobuf.snk + true diff --git a/csharp/src/Google.Protobuf/IMessage.cs b/csharp/src/Google.Protobuf/IMessage.cs index 60c6f8c3..147c83ca 100644 --- a/csharp/src/Google.Protobuf/IMessage.cs +++ b/csharp/src/Google.Protobuf/IMessage.cs @@ -91,8 +91,9 @@ namespace Google.Protobuf /// /// Generic interface for a deeply cloneable type. - /// + /// /// + /// /// All generated messages implement this interface, but so do some non-message types. /// Additionally, due to the type constraint on T in , /// 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 4f89347d..bbba9b3b 100644 --- a/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs +++ b/csharp/src/Google.Protobuf/InvalidProtocolBufferException.cs @@ -45,7 +45,7 @@ namespace Google.Protobuf { } - public static InvalidProtocolBufferException TruncatedMessage() + internal static InvalidProtocolBufferException TruncatedMessage() { return new InvalidProtocolBufferException( "While parsing a protocol message, the input ended unexpectedly " + @@ -61,12 +61,15 @@ namespace Google.Protobuf "which claimed to have negative size."); } - public static InvalidProtocolBufferException MalformedVarint() + internal static InvalidProtocolBufferException MalformedVarint() { return new InvalidProtocolBufferException( "CodedInputStream encountered a malformed varint."); } + /// + /// Creates an exception for an error condition of an invalid tag being encountered. + /// public static InvalidProtocolBufferException InvalidTag() { return new InvalidProtocolBufferException( diff --git a/csharp/src/Google.Protobuf/JsonFormatter.cs b/csharp/src/Google.Protobuf/JsonFormatter.cs index 999e106c..edc47186 100644 --- a/csharp/src/Google.Protobuf/JsonFormatter.cs +++ b/csharp/src/Google.Protobuf/JsonFormatter.cs @@ -114,11 +114,20 @@ namespace Google.Protobuf private readonly Settings settings; + /// + /// Creates a new formatted with the given settings. + /// + /// The settings. public JsonFormatter(Settings settings) { this.settings = settings; } + /// + /// Formats the specified message as JSON. + /// + /// The message to format. + /// The formatted message. public string Format(IMessage message) { Preconditions.CheckNotNull(message, "message"); @@ -768,6 +777,10 @@ namespace Google.Protobuf /// public bool FormatDefaultValues { get { return formatDefaultValues; } } + /// + /// Creates a new object with the specified formatting of default values. + /// + /// true if default values (0, empty strings etc) should be formatted; false otherwise. public Settings(bool formatDefaultValues) { this.formatDefaultValues = formatDefaultValues; diff --git a/csharp/src/Google.Protobuf/MessageExtensions.cs b/csharp/src/Google.Protobuf/MessageExtensions.cs index 6e7d47bc..ee78dc8d 100644 --- a/csharp/src/Google.Protobuf/MessageExtensions.cs +++ b/csharp/src/Google.Protobuf/MessageExtensions.cs @@ -39,6 +39,11 @@ namespace Google.Protobuf /// public static class MessageExtensions { + /// + /// Merges data from the given byte array into an existing message. + /// + /// The message to merge the data into. + /// The data to merge, which must be protobuf-encoded binary data. public static void MergeFrom(this IMessage message, byte[] data) { Preconditions.CheckNotNull(message, "message"); @@ -48,6 +53,11 @@ namespace Google.Protobuf input.CheckLastTagWas(0); } + /// + /// Merges data from the given byte string into an existing message. + /// + /// The message to merge the data into. + /// The data to merge, which must be protobuf-encoded binary data. public static void MergeFrom(this IMessage message, ByteString data) { Preconditions.CheckNotNull(message, "message"); @@ -57,6 +67,11 @@ namespace Google.Protobuf input.CheckLastTagWas(0); } + /// + /// Merges data from the given stream into an existing message. + /// + /// The message to merge the data into. + /// Stream containing the data to merge, which must be protobuf-encoded binary data. public static void MergeFrom(this IMessage message, Stream input) { Preconditions.CheckNotNull(message, "message"); @@ -66,6 +81,15 @@ namespace Google.Protobuf codedInput.CheckLastTagWas(0); } + /// + /// Merges length-delimited data from the given stream into an existing message. + /// + /// + /// The stream is expected to contain a length and then the data. Only the amount of data + /// specified by the length will be consumed. + /// + /// The message to merge the data into. + /// Stream containing the data to merge, which must be protobuf-encoded binary data. public static void MergeDelimitedFrom(this IMessage message, Stream input) { Preconditions.CheckNotNull(message, "message"); @@ -75,6 +99,11 @@ namespace Google.Protobuf message.MergeFrom(limitedStream); } + /// + /// Converts the given message into a byte array in protobuf encoding. + /// + /// The message to convert. + /// The message data as a byte array. public static byte[] ToByteArray(this IMessage message) { Preconditions.CheckNotNull(message, "message"); @@ -85,6 +114,11 @@ namespace Google.Protobuf return result; } + /// + /// Writes the given message data to the given stream in protobuf encoding. + /// + /// The message to write to the stream. + /// The stream to write to. public static void WriteTo(this IMessage message, Stream output) { Preconditions.CheckNotNull(message, "message"); @@ -94,6 +128,11 @@ namespace Google.Protobuf codedOutput.Flush(); } + /// + /// Writes the length and then data of the given message to a stream. + /// + /// The message to write. + /// The output stream to write to. public static void WriteDelimitedTo(this IMessage message, Stream output) { Preconditions.CheckNotNull(message, "message"); @@ -104,6 +143,11 @@ namespace Google.Protobuf codedOutput.Flush(); } + /// + /// Converts the given message into a byte string in protobuf encoding. + /// + /// The message to convert. + /// The message data as a byte string. 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 bfa63ae5..6a6f1017 100644 --- a/csharp/src/Google.Protobuf/MessageParser.cs +++ b/csharp/src/Google.Protobuf/MessageParser.cs @@ -90,6 +90,11 @@ namespace Google.Protobuf return message; } + /// + /// Parses a message from the given byte string. + /// + /// The data to parse. + /// The parsed message. public T ParseFrom(ByteString data) { Preconditions.CheckNotNull(data, "data"); @@ -98,6 +103,11 @@ namespace Google.Protobuf return message; } + /// + /// Parses a message from the given stream. + /// + /// The stream to parse. + /// The parsed message. public T ParseFrom(Stream input) { T message = factory(); @@ -105,6 +115,15 @@ namespace Google.Protobuf return message; } + /// + /// Parses a length-delimited message from the given stream. + /// + /// + /// The stream is expected to contain a length and then the data. Only the amount of data + /// specified by the length will be consumed. + /// + /// The stream to parse. + /// The parsed message. public T ParseDelimitedFrom(Stream input) { T message = factory(); @@ -112,6 +131,11 @@ namespace Google.Protobuf return message; } + /// + /// Parses a message from the given coded input stream. + /// + /// The stream to parse. + /// The parsed message. 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 0300cd58..194041a8 100644 --- a/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs +++ b/csharp/src/Google.Protobuf/Reflection/DescriptorBase.cs @@ -61,6 +61,9 @@ namespace Google.Protobuf.Reflection get { return index; } } + /// + /// Returns the name of the entity (field, message etc) being described. + /// public abstract string Name { get; } /// diff --git a/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs index 29833c4a..b212ce96 100644 --- a/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs +++ b/csharp/src/Google.Protobuf/Reflection/EnumValueDescriptor.cs @@ -51,11 +51,20 @@ namespace Google.Protobuf.Reflection } internal EnumValueDescriptorProto Proto { get { return proto; } } - + + /// + /// Returns the name of the enum value described by this object. + /// public override string Name { get { return proto.Name; } } + /// + /// Returns the number associated with this enum value. + /// public int Number { get { return Proto.Number; } } + /// + /// Returns the enum descriptor that this value is part of. + /// 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 60f2bb8b..bb8e9bbb 100644 --- a/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs +++ b/csharp/src/Google.Protobuf/Reflection/FieldDescriptor.cs @@ -93,6 +93,15 @@ namespace Google.Protobuf.Reflection internal FieldDescriptorProto Proto { get { return proto; } } + /// + /// Returns the accessor for this field, or null if this descriptor does + /// not support reflective access. + /// + /// + /// While a 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. + /// public IFieldAccessor Accessor { get { return accessor; } } /// @@ -141,43 +150,61 @@ namespace Google.Protobuf.Reflection default: throw new ArgumentException("Invalid type specified"); } - } + } + /// + /// Returns true if this field is a repeated field; false otherwise. + /// public bool IsRepeated { get { return Proto.Label == FieldDescriptorProto.Types.Label.LABEL_REPEATED; } } + /// + /// Returns true if this field is a map field; false otherwise. + /// 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... + + /// + /// Returns true if this field is a packed, repeated field; false otherwise. + /// public bool IsPacked { get { return Proto.Options != null && Proto.Options.Packed; } } /// - /// Get the field's containing type. For extensions, this is the type being - /// extended, not the location where the extension was defined. See - /// . + /// Get the field's containing message type. /// public MessageDescriptor ContainingType { get { return containingType; } } + /// + /// Returns the oneof containing this field, or null if it is not part of a oneof. + /// public OneofDescriptor ContainingOneof { get { return containingOneof; } - } + } + /// + /// Returns the type of the field. + /// public FieldType FieldType { get { return fieldType; } } + /// + /// Returns the field number declared in the proto file. + /// 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 41fa702d..1658e34c 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 { /// - /// 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. /// public enum FieldType { + /// + /// The double field type. + /// Double, + /// + /// The float field type. + /// Float, + /// + /// The int64 field type. + /// Int64, + /// + /// The uint64 field type. + /// UInt64, + /// + /// The int32 field type. + /// Int32, + /// + /// The fixed64 field type. + /// Fixed64, + /// + /// The fixed32 field type. + /// Fixed32, + /// + /// The bool field type. + /// Bool, + /// + /// The string field type. + /// String, + /// + /// The field type used for groups (not supported in this implementation). + /// Group, + /// + /// The field type used for message fields. + /// Message, + /// + /// The bytes field type. + /// Bytes, + /// + /// The uint32 field type. + /// UInt32, + /// + /// The sfixed32 field type. + /// SFixed32, + /// + /// The sfixed64 field type. + /// SFixed64, + /// + /// The sint32 field type. + /// SInt32, + /// + /// The sint64 field type. + /// SInt64, + /// + /// The field type used for enum fields. + /// 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 c17c4cc4..72927702 100644 --- a/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs +++ b/csharp/src/Google.Protobuf/Reflection/FileDescriptor.cs @@ -51,18 +51,7 @@ namespace Google.Protobuf.Reflection private readonly IList dependencies; private readonly IList 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 @@ namespace Google.Protobuf.Reflection throw new ArgumentException("Invalid embedded descriptor for \"" + proto.Name + "\".", e); } } - + + /// + /// Returns a that represents this instance. + /// + /// + /// A that represents this instance. + /// 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 6506db1b..318d58c9 100644 --- a/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs +++ b/csharp/src/Google.Protobuf/Reflection/IDescriptor.cs @@ -37,8 +37,19 @@ namespace Google.Protobuf.Reflection /// public interface IDescriptor { + /// + /// Returns the name of the entity (message, field etc) being described. + /// string Name { get; } + + /// + /// Returns the fully-qualified name of the entity being described. + /// string FullName { get; } + + /// + /// Returns the descriptor for the .proto file that this entity is part of. + /// 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 3f4f05f4..f97d73ee 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 { /// @@ -64,7 +67,7 @@ namespace Google.Protobuf.Reflection /// 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. /// - /// The field is not a "simple" field, or the message is frozen. + /// The field is not a "simple" field. 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 0b562de1..82901f1b 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 @@ namespace Google.Protobuf.Reflection get { return enumTypes; } } + /// + /// An unmodifiable list of the "oneof" field collections in this message type. + /// public IList Oneofs { get { return oneofs; } @@ -276,7 +278,7 @@ namespace Google.Protobuf.Reflection /// /// Retrieves the descriptor for the field with the given name. /// - /// Number of the field to retrieve the descriptor for + /// Name of the field to retrieve the descriptor for /// The descriptor for the given field /// The message descriptor does not contain a field /// with the given name diff --git a/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs b/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs index 8631a1c5..ff51291b 100644 --- a/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs +++ b/csharp/src/Google.Protobuf/Reflection/OneofAccessor.cs @@ -58,6 +58,12 @@ namespace Google.Protobuf.Reflection clearDelegate = ReflectionUtil.CreateActionObject(clearMethod); } + /// + /// Gets the descriptor for this oneof. + /// + /// + /// The descriptor of the oneof. + /// public OneofDescriptor Descriptor { get { return descriptor; } } /// diff --git a/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs b/csharp/src/Google.Protobuf/Reflection/OneofDescriptor.cs index 8571a5eb..d51ee526 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 { + /// + /// 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. + /// public sealed class OneofDescriptor : DescriptorBase { private readonly OneofDescriptorProto proto; @@ -59,13 +62,33 @@ namespace Google.Protobuf.Reflection /// public override string Name { get { return proto.Name; } } + /// + /// Gets the message type containing this oneof. + /// + /// + /// The message type containing this oneof. + /// public MessageDescriptor ContainingType { get { return containingType; } } + /// + /// Gets the fields within this oneof, in declaration order. + /// + /// + /// The fields within this oneof, in declaration order. + /// public IList Fields { get { return fields; } } + /// + /// Gets an accessor for reflective access to the values associated with the oneof + /// in a particular message. + /// + /// + /// The accessor used for reflective access, or null if reflection is not + /// supported by this descriptor. + /// 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 c69d1b23..18ebefd2 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/DurationPartial.cs @@ -38,7 +38,13 @@ namespace Google.Protobuf.WellKnownTypes // providing a conversion to TimeSpan and convenience operators. public partial class Duration { + /// + /// The number of nanoseconds in a second. + /// public const int NanosecondsPerSecond = 1000000000; + /// + /// The number of nanoseconds in a BCL tick (as used by and ). + /// public const int NanosecondsPerTick = 100; /// diff --git a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs index a3806b5c..dd485d32 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimeExtensions.cs @@ -43,16 +43,35 @@ namespace Google.Protobuf.WellKnownTypes /// public static class TimeExtensions { + /// + /// Converts the given to a . + /// + /// The date and time to convert to a timestamp. + /// The value has a other than Utc. + /// The converted timestamp. public static Timestamp ToTimestamp(this DateTime dateTime) { return Timestamp.FromDateTime(dateTime); } + /// + /// Converts the given to a + /// + /// 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 DateTimeOffset. + /// The date and time (with UTC offset) to convert to a timestamp. + /// The converted timestamp. public static Timestamp ToTimestamp(this DateTimeOffset dateTimeOffset) { return Timestamp.FromDateTimeOffset(dateTimeOffset); } + /// + /// Converts the given to a . + /// + /// The time span to convert. + /// The converted duration. 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 1aa392c7..68584358 100644 --- a/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs +++ b/csharp/src/Google.Protobuf/WellKnownTypes/TimestampPartial.cs @@ -136,9 +136,12 @@ namespace Google.Protobuf.WellKnownTypes } /// - /// Converts the specified to a . + /// Converts the given to a /// - /// + /// 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 DateTimeOffset. + /// The date and time (with UTC offset) to convert to a timestamp. /// The converted timestamp. public static Timestamp FromDateTimeOffset(DateTimeOffset dateTimeOffset) { diff --git a/csharp/src/Google.Protobuf/WireFormat.cs b/csharp/src/Google.Protobuf/WireFormat.cs index c1712daa..bbd7e4f9 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 { /// @@ -59,13 +56,34 @@ namespace Google.Protobuf #endregion + /// + /// Wire types within protobuf encoding. + /// public enum WireType : uint { + /// + /// Variable-length integer. + /// Varint = 0, + /// + /// A fixed-length 64-bit value. + /// Fixed64 = 1, + /// + /// A length-delimited value, i.e. a length followed by that many bytes of data. + /// LengthDelimited = 2, + /// + /// A "start group" value - not supported by this implementation. + /// StartGroup = 3, + /// + /// An "end group" value - not supported by this implementation. + /// EndGroup = 4, + /// + /// A fixed-length 32-bit value. + /// Fixed32 = 5 } @@ -80,6 +98,11 @@ namespace Google.Protobuf return (WireType) (tag & TagTypeMask); } + /// + /// Determines whether the given tag is an end group tag. + /// + /// The tag to check. + /// true if the given tag is an end group tag; false otherwise. public static bool IsEndGroupTag(uint tag) { return (WireType) (tag & TagTypeMask) == WireType.EndGroup; @@ -99,64 +122,6 @@ namespace Google.Protobuf 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)); - } - - /// - /// Returns the wire type for the given field descriptor. This differs - /// from GetWireType(FieldType) for packed repeated fields. - /// - internal static WireType GetWireType(FieldDescriptor descriptor) - { - return descriptor.IsPacked ? WireType.LengthDelimited : GetWireType(descriptor.FieldType); - } - - /// - /// 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. - /// - 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 -- cgit v1.2.3