Add documentation in generated code

Fixes stepancheg#402

Author: mcarton

protobuf-codegen/src/code_writer.rs

@@ -270,6 +270,85 @@ impl<'a> CodeWriter<'a> {
         }
     }
 
+    fn documentation(&mut self, comment: &str) {
+        if comment.is_empty() {
+            self.write_line("///");
+        } else {
+            self.write_line(&format!("/// {}", comment));
+        }
+    }
+
+    /// Writes the documentation of the given path.
+    ///
+    /// Protobuf paths are defined in proto/google/protobuf/descriptor.proto,
+    /// in the `SourceCodeInfo` message.
+    ///
+    /// For example, say we have a file like:
+    ///
+    /// ```ignore
+    /// message Foo {
+    ///   optional string foo = 1;
+    /// }
+    /// ```
+    ///
+    /// Let's look at just the field definition. We have the following paths:
+    ///
+    /// ```ignore
+    /// path               represents
+    /// [ 4, 0, 2, 0 ]     The whole field definition.
+    /// [ 4, 0, 2, 0, 4 ]  The label (optional).
+    /// [ 4, 0, 2, 0, 5 ]  The type (string).
+    /// [ 4, 0, 2, 0, 1 ]  The name (foo).
+    /// [ 4, 0, 2, 0, 3 ]  The number (1).
+    /// ```
+    ///
+    /// The `4`s can be obtained using simple introspection:
+    ///
+    /// ```
+    /// use protobuf::descriptor::FileDescriptorProto;
+    /// use protobuf::reflect::MessageDescriptor;
+    ///
+    /// let id = MessageDescriptor::for_type::<FileDescriptorProto>()
+    ///     .field_by_name("message_type")
+    ///     .expect("`message_type` must exist")
+    ///     .proto()
+    ///     .get_number();
+    ///
+    /// assert_eq!(id, 4);
+    /// ```
+    ///
+    /// The first `0` here means this path refers to the first message.
+    ///
+    /// The `2` then refers to the `field` field on the `DescriptorProto` message.
+    ///
+    /// Then comes another `0` to refer to the first field of the current message.
+    ///
+    /// Etc.
+
+    pub fn all_documentation(
+        &mut self,
+        info: Option<&protobuf::descriptor::SourceCodeInfo>,
+        path: &[i32],
+    ) {
+        let doc = info
+            .map(|v| &v.location)
+            .and_then(|ls| ls.iter().find(|l| l.path == path))
+            .map(|l| l.get_leading_comments());
+
+        let lines = doc
+            .iter()
+            .map(|doc| doc.lines())
+            .flatten()
+            .collect::<Vec<_>>();
+
+        // Skip comments with code blocks to avoid rustdoc trying to compile them.
+        if !lines.iter().any(|line| line.starts_with("    ")) {
+            for doc in &lines {
+                self.documentation(doc);
+            }
+        }
+    }
+
     pub fn fn_def(&mut self, sig: &str) {
         self.write_line(&format!("fn {};", sig));
     }

protobuf-codegen/src/enums.rs

@@ -55,13 +55,17 @@ pub(crate) struct EnumGen<'a> {
     type_name: RustIdentWithPath,
     lite_runtime: bool,
     customize: Customize,
+    path: &'a [i32],
+    info: Option<&'a SourceCodeInfo>,
 }
 
 impl<'a> EnumGen<'a> {
     pub fn new(
         enum_with_scope: &'a EnumWithScope<'a>,
         customize: &Customize,
         _root_scope: &RootScope,
+        path: &'a [i32],
+        info: Option<&'a SourceCodeInfo>,
     ) -> EnumGen<'a> {
         let lite_runtime = customize.lite_runtime.unwrap_or_else(|| {
             enum_with_scope
@@ -78,6 +82,8 @@ impl<'a> EnumGen<'a> {
             type_name: enum_with_scope.rust_name().to_path(),
             lite_runtime,
             customize: customize.clone(),
+            path,
+            info,
         }
     }
 
@@ -112,7 +118,7 @@ impl<'a> EnumGen<'a> {
     }
 
     pub fn write(&self, w: &mut CodeWriter) {
-        self.write_struct(w);
+        self.write_enum(w);
         if self.allow_alias() {
             w.write_line("");
             self.write_impl_eq(w);
@@ -127,7 +133,9 @@ impl<'a> EnumGen<'a> {
         self.write_impl_value(w);
     }
 
-    fn write_struct(&self, w: &mut CodeWriter) {
+    fn write_enum(&self, w: &mut CodeWriter) {
+        w.all_documentation(self.info, self.path);
+
         let mut derive = Vec::new();
         derive.push("Clone");
         derive.push("Copy");

protobuf-codegen/src/field.rs

@@ -580,13 +580,17 @@ pub(crate) struct FieldGen<'a> {
     pub generate_accessors: bool,
     pub generate_getter: bool,
     customize: Customize,
+    path: Vec<i32>,
+    info: Option<&'a SourceCodeInfo>,
 }
 
 impl<'a> FieldGen<'a> {
     pub fn parse(
         field: FieldWithContext<'a>,
         root_scope: &'a RootScope<'a>,
         customize: &Customize,
+        path: Vec<i32>,
+        info: Option<&'a SourceCodeInfo>,
     ) -> FieldGen<'a> {
         let mut customize = customize.clone();
         customize.update_with(&customize_from_rustproto_for_field(
@@ -691,6 +695,8 @@ impl<'a> FieldGen<'a> {
             generate_accessors,
             generate_getter,
             customize,
+            path,
+            info,
         }
     }
 
@@ -1454,6 +1460,8 @@ impl<'a> FieldGen<'a> {
         if self.proto_type == field_descriptor_proto::Type::TYPE_GROUP {
             w.comment(&format!("{}: <group>", &self.rust_name));
         } else {
+            w.all_documentation(self.info, &self.path);
+
             let vis = self.visibility();
             w.field_decl_vis(
                 vis,

protobuf-codegen/src/lib.rs

@@ -191,16 +191,55 @@ fn gen_file(
             ));
         }
 
-        for message in &scope.get_messages() {
+        static NESTED_TYPE_NUMBER: protobuf::rt::Lazy<i32> = protobuf::rt::Lazy::INIT;
+        let message_type_number = *NESTED_TYPE_NUMBER.get(|| {
+            protobuf::reflect::MessageDescriptor::for_type::<FileDescriptorProto>()
+                .field_by_name("message_type")
+                .expect("`message_type` must exist")
+                .proto()
+                .get_number()
+        });
+
+        let mut path = vec![message_type_number, 0];
+        for (id, message) in scope.get_messages().iter().enumerate() {
             // ignore map entries, because they are not used in map fields
             if map_entry(message).is_none() {
+                path[1] = id as i32;
+
                 w.write_line("");
-                MessageGen::new(message, &root_scope, &customize).write(&mut w);
+                MessageGen::new(
+                    message,
+                    &root_scope,
+                    &customize,
+                    &path,
+                    file.source_code_info.as_ref(),
+                )
+                .write(&mut w);
             }
         }
-        for enum_type in &scope.get_enums() {
+
+        static ENUM_TYPE_NUMBER: protobuf::rt::Lazy<i32> = protobuf::rt::Lazy::INIT;
+        let enum_type_number = *ENUM_TYPE_NUMBER.get(|| {
+            protobuf::reflect::MessageDescriptor::for_type::<FileDescriptorProto>()
+                .field_by_name("enum_type")
+                .expect("`enum_type` must exist")
+                .proto()
+                .get_number()
+        });
+
+        let mut path = vec![enum_type_number, 0];
+        for (id, enum_type) in scope.get_enums().iter().enumerate() {
+            path[1] = id as i32;
+
             w.write_line("");
-            EnumGen::new(enum_type, &customize, root_scope).write(&mut w);
+            EnumGen::new(
+                enum_type,
+                &customize,
+                root_scope,
+                &path,
+                file.source_code_info.as_ref(),
+            )
+            .write(&mut w);
         }
 
         write_extensions(file, &root_scope, &mut w, &customize);

protobuf-codegen/src/message.rs

@@ -31,23 +31,41 @@ pub(crate) struct MessageGen<'a> {
     pub fields: Vec<FieldGen<'a>>,
     pub lite_runtime: bool,
     customize: Customize,
+    path: &'a [i32],
+    info: Option<&'a SourceCodeInfo>,
 }
 
 impl<'a> MessageGen<'a> {
     pub fn new(
         message: &'a MessageWithScope<'a>,
         root_scope: &'a RootScope<'a>,
         customize: &Customize,
+        path: &'a [i32],
+        info: Option<&'a SourceCodeInfo>,
     ) -> MessageGen<'a> {
         let mut customize = customize.clone();
         customize.update_with(&customize_from_rustproto_for_message(
             message.message.options.get_message(),
         ));
 
+        static FIELD_NUMBER: protobuf::rt::Lazy<i32> = protobuf::rt::Lazy::INIT;
+        let field_number = *FIELD_NUMBER.get(|| {
+            protobuf::reflect::MessageDescriptor::for_type::<DescriptorProto>()
+                .field_by_name("field")
+                .expect("`field` must exist")
+                .proto()
+                .get_number()
+        });
+
         let fields: Vec<_> = message
             .fields()
             .into_iter()
-            .map(|field| FieldGen::parse(field, root_scope, &customize))
+            .enumerate()
+            .map(|(id, field)| {
+                let mut path = path.to_vec();
+                path.extend_from_slice(&[field_number, id as i32]);
+                FieldGen::parse(field, root_scope, &customize, path, info)
+            })
             .collect();
         let lite_runtime = customize.lite_runtime.unwrap_or_else(|| {
             message
@@ -64,6 +82,8 @@ impl<'a> MessageGen<'a> {
             fields: fields,
             lite_runtime,
             customize,
+            path,
+            info,
         }
     }
 
@@ -527,6 +547,7 @@ impl<'a> MessageGen<'a> {
     }
 
     pub fn write(&self, w: &mut CodeWriter) {
+        w.all_documentation(self.info, self.path);
         self.write_struct(w);
 
         w.write_line("");
@@ -579,20 +600,56 @@ impl<'a> MessageGen<'a> {
                     oneof.write(w);
                 }
 
-                for nested in &nested_messages {
+                static NESTED_TYPE_NUMBER: protobuf::rt::Lazy<i32> = protobuf::rt::Lazy::INIT;
+                let nested_type_number = *NESTED_TYPE_NUMBER.get(|| {
+                    protobuf::reflect::MessageDescriptor::for_type::<DescriptorProto>()
+                        .field_by_name("nested_type")
+                        .expect("`nested_type` must exist")
+                        .proto()
+                        .get_number()
+                });
+
+                let mut path = self.path.to_vec();
+                path.extend(&[nested_type_number, 0]);
+                for (id, nested) in nested_messages.iter().enumerate() {
+                    let len = path.len() - 1;
+                    path[len] = id as i32;
+
                     if !first {
                         w.write_line("");
                     }
                     first = false;
-                    MessageGen::new(nested, self.root_scope, &self.customize).write(w);
+                    MessageGen::new(nested, self.root_scope, &self.customize, &path, self.info)
+                        .write(w);
                 }
 
-                for enum_type in &self.message.to_scope().get_enums() {
+                static ENUM_TYPE_NUMBER: protobuf::rt::Lazy<i32> = protobuf::rt::Lazy::INIT;
+                let enum_type_number = *ENUM_TYPE_NUMBER.get(|| {
+                    protobuf::reflect::MessageDescriptor::for_type::<DescriptorProto>()
+                        .field_by_name("enum_type")
+                        .expect("`enum_type` must exist")
+                        .proto()
+                        .get_number()
+                });
+
+                let len = path.len() - 2;
+                path[len] = enum_type_number;
+                for (id, enum_type) in self.message.to_scope().get_enums().iter().enumerate() {
+                    let len = path.len() - 1;
+                    path[len] = id as i32;
+
                     if !first {
                         w.write_line("");
                     }
                     first = false;
-                    EnumGen::new(enum_type, &self.customize, self.root_scope).write(w);
+                    EnumGen::new(
+                        enum_type,
+                        &self.customize,
+                        self.root_scope,
+                        &path,
+                        self.info,
+                    )
+                    .write(w);
                 }
             });
         }