def FormatCommentWithAnnotations(comment, type_name=''):
"""Format a comment string with additional RST for annotations.
Args:
comment: comment string.
type_name: optional, 'message' or 'enum' may be specified for additional
message/enum specific annotations.
Returns:
A string with additional RST from annotations.
"""
s = annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n')
if annotations.NOT_IMPLEMENTED_WARN_ANNOTATION in comment.annotations:
s += '\n.. WARNING::\n Not implemented yet\n'
if annotations.V2_API_DIFF_ANNOTATION in comment.annotations:
s += '\n.. NOTE::\n **v2 API difference**: ' + comment.annotations[
annotations.V2_API_DIFF_ANNOTATION] + '\n'
if type_name == 'message' or type_name == 'enum':
if annotations.PROTO_STATUS_ANNOTATION in comment.annotations:
status = comment.annotations[annotations.PROTO_STATUS_ANNOTATION]
if status not in ['frozen', 'draft', 'experimental']:
raise ProtodocError('Unknown proto status: %s' % status)
if status == 'draft' or status == 'experimental':
s += ('\n.. WARNING::\n This %s type has :ref:`%s '
'<config_overview_v2_status>` status.\n' %
(type_name, status))
return s
def FormatHeaderFromFile(style, source_code_info, proto_name):
"""Format RST header based on special file level title
Args:
style: underline style, e.g. '=', '-'.
source_code_info: SourceCodeInfo object.
proto_name: If the file_level_comment does not contain a user specified
title, use this as page title.
Returns:
RST formatted header, and file level comment without page title strings.
"""
anchor = FormatAnchor(FileCrossRefLabel(proto_name))
stripped_comment = annotations.WithoutAnnotations(
StripLeadingSpace('\n'.join(
c + '\n' for c in source_code_info.file_level_comments)))
formatted_extension = ''
if annotations.EXTENSION_ANNOTATION in source_code_info.file_level_annotations:
extension = source_code_info.file_level_annotations[
annotations.EXTENSION_ANNOTATION]
formatted_extension = FormatExtension(extension)
if annotations.DOC_TITLE_ANNOTATION in source_code_info.file_level_annotations:
return anchor + FormatHeader(
style, source_code_info.file_level_annotations[
annotations.DOC_TITLE_ANNOTATION]
) + formatted_extension, stripped_comment
return anchor + FormatHeader(
style, proto_name) + formatted_extension, stripped_comment
def FormatCommentWithAnnotations(comment, type_name=''):
"""Format a comment string with additional RST for annotations.
Args:
comment: comment string.
type_name: optional, 'message' or 'enum' may be specified for additional
message/enum specific annotations.
Returns:
A string with additional RST from annotations.
"""
return annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n')
def FormatCommentWithAnnotations(comment, type_name=''):
"""Format a comment string with additional RST for annotations.
Args:
comment: comment string.
type_name: optional, 'message' or 'enum' may be specified for additional
message/enum specific annotations.
Returns:
A string with additional RST from annotations.
"""
formatted_extension = ''
if annotations.EXTENSION_ANNOTATION in comment.annotations:
extension = comment.annotations[annotations.EXTENSION_ANNOTATION]
formatted_extension = FormatExtension(extension)
return annotations.WithoutAnnotations(StripLeadingSpace(comment.raw) + '\n') + formatted_extension
def FormatCommentWithAnnotations(comment, type_name=''):
"""Format a comment string with additional RST for annotations.
Args:
comment: comment string.
type_name: optional, 'message' or 'enum' may be specified for additional
message/enum specific annotations.
Returns:
A string with additional RST from annotations.
"""
formatted_extension = ''
if annotations.EXTENSION_ANNOTATION in comment.annotations:
extension = comment.annotations[annotations.EXTENSION_ANNOTATION]
formatted_extension = FormatExtension(extension)
formatted_extension_category = ''
if annotations.EXTENSION_CATEGORY_ANNOTATION in comment.annotations:
for category in comment.annotations[
annotations.EXTENSION_CATEGORY_ANNOTATION].split(","):
formatted_extension_category += FormatExtensionCategory(category)
comment = annotations.WithoutAnnotations(
StripLeadingSpace(comment.raw) + '\n')
return comment + formatted_extension + formatted_extension_category
