1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc. All rights reserved.
3// https://developers.google.com/protocol-buffers/
4//
5// Redistribution and use in source and binary forms, with or without
6// modification, are permitted provided that the following conditions are
7// met:
8//
9// * Redistributions of source code must retain the above copyright
10// notice, this list of conditions and the following disclaimer.
11// * Redistributions in binary form must reproduce the above
12// copyright notice, this list of conditions and the following disclaimer
13// in the documentation and/or other materials provided with the
14// distribution.
15// * Neither the name of Google Inc. nor the names of its
16// contributors may be used to endorse or promote products derived from
17// this software without specific prior written permission.
18//
19// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
24// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
25// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
26// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
27// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
28// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30
31// Author: kenton@google.com (Kenton Varda)
32// Based on original Protocol Buffers design by
33// Sanjay Ghemawat, Jeff Dean, and others.
34#include <google/protobuf/compiler/csharp/csharp_doc_comment.h>
35#include <google/protobuf/descriptor.h>
36#include <google/protobuf/io/printer.h>
37#include <google/protobuf/stubs/strutil.h>
38
39namespace google {
40namespace protobuf {
41namespace compiler {
42namespace csharp {
43
44// Functions to create C# XML documentation comments.
45// Currently this only includes documentation comments containing text specified as comments
46// in the .proto file; documentation comments generated just from field/message/enum/proto names
47// is inlined in the relevant code. If more control is required, that code can be moved here.
48
49void WriteDocCommentBodyImpl(io::Printer* printer, SourceLocation location) {
50 std::string comments = location.leading_comments.empty() ?
51 location.trailing_comments : location.leading_comments;
52 if (comments.empty()) {
53 return;
54 }
55 // XML escaping... no need for apostrophes etc as the whole text is going to be a child
56 // node of a summary element, not part of an attribute.
57 comments = StringReplace(s: comments, oldsub: "&", newsub: "&amp;", replace_all: true);
58 comments = StringReplace(s: comments, oldsub: "<", newsub: "&lt;", replace_all: true);
59 std::vector<std::string> lines;
60 lines = Split(full: comments, delim: "\n", skip_empty: false);
61 // TODO: We really should work out which part to put in the summary and which to put in the remarks...
62 // but that needs to be part of a bigger effort to understand the markdown better anyway.
63 printer->Print(text: "/// <summary>\n");
64 bool last_was_empty = false;
65 // We squash multiple blank lines down to one, and remove any trailing blank lines. We need
66 // to preserve the blank lines themselves, as this is relevant in the markdown.
67 // Note that we can't remove leading or trailing whitespace as *that's* relevant in markdown too.
68 // (We don't skip "just whitespace" lines, either.)
69 for (std::vector<std::string>::iterator it = lines.begin();
70 it != lines.end(); ++it) {
71 std::string line = *it;
72 if (line.empty()) {
73 last_was_empty = true;
74 } else {
75 if (last_was_empty) {
76 printer->Print(text: "///\n");
77 }
78 last_was_empty = false;
79 printer->Print(text: "///$line$\n", args: "line", args: *it);
80 }
81 }
82 printer->Print(text: "/// </summary>\n");
83}
84
85template <typename DescriptorType>
86static void WriteDocCommentBody(
87 io::Printer* printer, const DescriptorType* descriptor) {
88 SourceLocation location;
89 if (descriptor->GetSourceLocation(&location)) {
90 WriteDocCommentBodyImpl(printer, location);
91 }
92}
93
94void WriteMessageDocComment(io::Printer* printer, const Descriptor* message) {
95 WriteDocCommentBody(printer, descriptor: message);
96}
97
98void WritePropertyDocComment(io::Printer* printer, const FieldDescriptor* field) {
99 WriteDocCommentBody(printer, descriptor: field);
100}
101
102void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enumDescriptor) {
103 WriteDocCommentBody(printer, descriptor: enumDescriptor);
104}
105void WriteEnumValueDocComment(io::Printer* printer, const EnumValueDescriptor* value) {
106 WriteDocCommentBody(printer, descriptor: value);
107}
108
109void WriteMethodDocComment(io::Printer* printer, const MethodDescriptor* method) {
110 WriteDocCommentBody(printer, descriptor: method);
111}
112
113} // namespace csharp
114} // namespace compiler
115} // namespace protobuf
116} // namespace google
117