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. --- .../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 +++++++++- 10 files changed, 157 insertions(+), 25 deletions(-) (limited to 'csharp/src/Google.Protobuf/Reflection') 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() -- cgit v1.2.3