1// Protocol Buffers - Google's data interchange format
2// Copyright 2008 Google Inc.  All rights reserved.
3// http://code.google.com/p/protobuf/
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
35#include <google/protobuf/compiler/java/java_doc_comment.h>
36
37#include <vector>
38
39#include <google/protobuf/io/printer.h>
40#include <google/protobuf/stubs/strutil.h>
41
42namespace google {
43namespace protobuf {
44namespace compiler {
45namespace java {
46
47string EscapeJavadoc(const string& input) {
48  string result;
49  result.reserve(input.size() * 2);
50
51  char prev = '*';
52
53  for (string::size_type i = 0; i < input.size(); i++) {
54    char c = input[i];
55    switch (c) {
56      case '*':
57        // Avoid "/*".
58        if (prev == '/') {
59          result.append("&#42;");
60        } else {
61          result.push_back(c);
62        }
63        break;
64      case '/':
65        // Avoid "*/".
66        if (prev == '*') {
67          result.append("&#47;");
68        } else {
69          result.push_back(c);
70        }
71        break;
72      case '@':
73        // "{@" starts Javadoc markup.
74        if (prev == '{') {
75          result.append("&#64;");
76        } else {
77          result.push_back(c);
78        }
79        break;
80      case '<':
81        // Avoid interpretation as HTML.
82        result.append("&lt;");
83        break;
84      case '>':
85        // Avoid interpretation as HTML.
86        result.append("&gt;");
87        break;
88      case '&':
89        // Avoid interpretation as HTML.
90        result.append("&amp;");
91        break;
92      case '\\':
93        // Java interprets Unicode escape sequences anywhere!
94        result.append("&#92;");
95        break;
96      default:
97        result.push_back(c);
98        break;
99    }
100
101    prev = c;
102  }
103
104  return result;
105}
106
107static void WriteDocCommentBodyForLocation(
108    io::Printer* printer, const SourceLocation& location) {
109  string comments = location.leading_comments.empty() ?
110      location.trailing_comments : location.leading_comments;
111  if (!comments.empty()) {
112    // TODO(kenton):  Ideally we should parse the comment text as Markdown and
113    //   write it back as HTML, but this requires a Markdown parser.  For now
114    //   we just use <pre> to get fixed-width text formatting.
115
116    // If the comment itself contains block comment start or end markers,
117    // HTML-escape them so that they don't accidentally close the doc comment.
118    comments = EscapeJavadoc(comments);
119
120    vector<string> lines;
121    SplitStringAllowEmpty(comments, "\n", &lines);
122    while (!lines.empty() && lines.back().empty()) {
123      lines.pop_back();
124    }
125
126    printer->Print(
127        " *\n"
128        " * <pre>\n");
129    for (int i = 0; i < lines.size(); i++) {
130      // Most lines should start with a space.  Watch out for lines that start
131      // with a /, since putting that right after the leading asterisk will
132      // close the comment.
133      if (!lines[i].empty() && lines[i][0] == '/') {
134        printer->Print(" * $line$\n", "line", lines[i]);
135      } else {
136        printer->Print(" *$line$\n", "line", lines[i]);
137      }
138    }
139    printer->Print(" * </pre>\n");
140  }
141}
142
143template <typename DescriptorType>
144static void WriteDocCommentBody(
145    io::Printer* printer, const DescriptorType* descriptor) {
146  SourceLocation location;
147  if (descriptor->GetSourceLocation(&location)) {
148    WriteDocCommentBodyForLocation(printer, location);
149  }
150}
151
152static string FirstLineOf(const string& value) {
153  string result = value;
154
155  string::size_type pos = result.find_first_of('\n');
156  if (pos != string::npos) {
157    result.erase(pos);
158  }
159
160  // If line ends in an opening brace, make it "{ ... }" so it looks nice.
161  if (!result.empty() && result[result.size() - 1] == '{') {
162    result.append(" ... }");
163  }
164
165  return result;
166}
167
168void WriteMessageDocComment(io::Printer* printer, const Descriptor* message) {
169  printer->Print(
170    "/**\n"
171    " * Protobuf type {@code $fullname$}\n",
172    "fullname", EscapeJavadoc(message->full_name()));
173  WriteDocCommentBody(printer, message);
174  printer->Print(" */\n");
175}
176
177void WriteFieldDocComment(io::Printer* printer, const FieldDescriptor* field) {
178  // In theory we should have slightly different comments for setters, getters,
179  // etc., but in practice everyone already knows the difference between these
180  // so it's redundant information.
181
182  // We use the field declaration as the first line of the comment, e.g.:
183  //   optional string foo = 5;
184  // This communicates a lot of information about the field in a small space.
185  // If the field is a group, the debug string might end with {.
186  printer->Print(
187    "/**\n"
188    " * <code>$def$</code>\n",
189    "def", EscapeJavadoc(FirstLineOf(field->DebugString())));
190  WriteDocCommentBody(printer, field);
191  printer->Print(" */\n");
192}
193
194void WriteEnumDocComment(io::Printer* printer, const EnumDescriptor* enum_) {
195  printer->Print(
196    "/**\n"
197    " * Protobuf enum {@code $fullname$}\n",
198    "fullname", EscapeJavadoc(enum_->full_name()));
199  WriteDocCommentBody(printer, enum_);
200  printer->Print(" */\n");
201}
202
203void WriteEnumValueDocComment(io::Printer* printer,
204                              const EnumValueDescriptor* value) {
205  printer->Print(
206    "/**\n"
207    " * <code>$def$</code>\n",
208    "def", EscapeJavadoc(FirstLineOf(value->DebugString())));
209  WriteDocCommentBody(printer, value);
210  printer->Print(" */\n");
211}
212
213void WriteServiceDocComment(io::Printer* printer,
214                            const ServiceDescriptor* service) {
215  printer->Print(
216    "/**\n"
217    " * Protobuf service {@code $fullname$}\n",
218    "fullname", EscapeJavadoc(service->full_name()));
219  WriteDocCommentBody(printer, service);
220  printer->Print(" */\n");
221}
222
223void WriteMethodDocComment(io::Printer* printer,
224                           const MethodDescriptor* method) {
225  printer->Print(
226    "/**\n"
227    " * <code>$def$</code>\n",
228    "def", EscapeJavadoc(FirstLineOf(method->DebugString())));
229  WriteDocCommentBody(printer, method);
230  printer->Print(" */\n");
231}
232
233}  // namespace java
234}  // namespace compiler
235}  // namespace protobuf
236}  // namespace google
237