Module: ProtoPlugin::Commentable

Included in:
EnumDescriptor, EnumValueDescriptor, FieldDescriptor, FileDescriptor, MessageDescriptor, MethodDescriptor, OneofDescriptor, ServiceDescriptor
Defined in:
lib/proto_plugin/commentable.rb

Overview

A mixin providing access to the comments associated with a descriptor via its file’s SourceCodeInfo.

Including classes must respond to #file (returning the FileDescriptor the element belongs to) and #descriptor (returning the raw descriptor proto the comments are keyed against).

See Also:

Instance Method Summary collapse

Instance Method Details

#comments ⇒ Array<String>

The comments attached to this element, in source order: the leading comment followed by the trailing comment. Absent blocks are omitted.

Detached comments (blocks the author separated from the element with a blank line) are not exposed. Per protoc they appear before “but [are] not connected to” the element, so they are file organization rather than documentation of any element.

Examples:

field.comments.join("\n").strip

Returns:

  • (Array<String>) 


52
53
54
 
# File 'lib/proto_plugin/commentable.rb', line 52

def comments
  [leading_comments, trailing_comments].compact
end

#leading_comments ⇒ String?

The comment block appearing directly above this element.

Returns:

  • (String) —

    the leading comment, as provided by protoc

  • (nil) —

    if there is no leading comment



27
28
29
 
# File 'lib/proto_plugin/commentable.rb', line 27

def leading_comments
  presence(source_location&.leading_comments)
end

#source_location ⇒ Google::Protobuf::SourceCodeInfo::Location?

The SourceCodeInfo::Location associated with this element, if source info was included in the request.

Returns:

  • (Google::Protobuf::SourceCodeInfo::Location)
  • (nil) —

    if no location is available



19
20
21
 
# File 'lib/proto_plugin/commentable.rb', line 19

def source_location
  file&.location_for(descriptor)
end

#trailing_comments ⇒ String?

The comment appearing directly after this element on the same or following line.

Returns:

  • (String) —

    the trailing comment, as provided by protoc

  • (nil) —

    if there is no trailing comment



36
37
38
 
# File 'lib/proto_plugin/commentable.rb', line 36

def trailing_comments
  presence(source_location&.trailing_comments)
end