1// https://github.com/apache/thrift/raw/master/test/DocTest.thrift
2/*
3 * Licensed to the Apache Software Foundation (ASF) under one
4 * or more contributor license agreements. See the NOTICE file
5 * distributed with this work for additional information
6 * regarding copyright ownership. The ASF licenses this file
7 * to you under the Apache License, Version 2.0 (the
8 * "License"); you may not use this file except in compliance
9 * with the License. You may obtain a copy of the License at
10 *
11 *   http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing,
14 * software distributed under the License is distributed on an
15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16 * KIND, either express or implied. See the License for the
17 * specific language governing permissions and limitations
18 * under the License.
19 */
20
21/**
22 * Program doctext.
23 *
24 * Seriously, this is the documentation for this whole program.
25 */
26
27namespace java thrift.test
28namespace cpp thrift.test
29
30// C++ comment
31/* c style comment */
32
33# the new unix comment
34
35/** Some doc text goes here.  Wow I am [nesting these] (no more nesting.) */
36enum Numberz
37{
38
39  /** This is how to document a parameter */
40  ONE = 1,
41
42  /** And this is a doc for a parameter that has no specific value assigned */
43  TWO,
44
45  THREE,
46  FIVE = 5,
47  SIX,
48  EIGHT = 8
49}
50
51/** This is how you would do a typedef doc */
52typedef i64 UserId
53
54/** And this is where you would document a struct */
55struct Xtruct
56{
57
58  /** And the members of a struct */
59  1:  string string_thing
60
61  /** doct text goes before a comma */
62  4:  i8     byte_thing,
63
64  9:  i32    i32_thing,
65  11: i64    i64_thing
66}
67
68/**
69 * You can document constants now too.  Yeehaw!
70 */
71const i32 INT32CONSTANT = 9853
72const i16 INT16CONSTANT = 1616
73/** Everyone get in on the docu-action! */
74const map<string,string> MAPCONSTANT = {'hello':'world', 'goodnight':'moon'}
75
76struct Xtruct2
77{
78  1: i8     byte_thing,
79  2: Xtruct struct_thing,
80  3: i32    i32_thing
81}
82
83/** Struct insanity */
84struct Insanity
85{
86
87  /** This is doc for field 1 */
88  1: map<Numberz, UserId> userMap,
89
90  /** And this is doc for field 2 */
91  2: list<Xtruct> xtructs
92}
93
94exception Xception {
95  1: i32 errorCode,
96  2: string message
97}
98
99exception Xception2 {
100  1: i32 errorCode,
101  2: Xtruct struct_thing
102}
103
104/* C1 */
105/** Doc */
106/* C2 */
107/* C3 */
108struct EmptyStruct {}
109
110struct OneField {
111  1: EmptyStruct field
112}
113
114/** This is where you would document a Service */
115service ThriftTest
116{
117
118  /** And this is how you would document functions in a service */
119  void         testVoid(),
120  string       testString(1: string thing),
121  i8           testByte(1: byte thing),
122  i32          testI32(1: i32 thing),
123
124  /** Like this one */
125  i64          testI64(1: i64 thing),
126  double       testDouble(1: double thing),
127  Xtruct       testStruct(1: Xtruct thing),
128  Xtruct2      testNest(1: Xtruct2 thing),
129  map<i32,i32> testMap(1: map<i32,i32> thing),
130  set<i32>     testSet(1: set<i32> thing),
131  list<i32>    testList(1: list<i32> thing),
132
133  /** This is an example of a function with params documented */
134  Numberz      testEnum(
135
136    /** This param is a thing */
137    1: Numberz thing
138
139  ),
140
141  UserId       testTypedef(1: UserId thing),
142
143  map<i32,map<i32,i32>> testMapMap(1: i32 hello),
144
145  /* So you think you've got this all worked, out eh? */
146  map<UserId, map<Numberz,Insanity>> testInsanity(1: Insanity argument),
147
148}
149
150/// This style of Doxy-comment doesn't work.
151typedef i32 SorryNoGo
152
153/**
154 * This is a trivial example of a multiline docstring.
155 */
156typedef i32 TrivialMultiLine
157
158/**
159 * This is the canonical example
160 * of a multiline docstring.
161 */
162typedef i32 StandardMultiLine
163
164/**
165 * The last line is non-blank.
166 * I said non-blank! */
167typedef i32 LastLine
168
169/** Both the first line
170 * are non blank. ;-)
171 * and the last line */
172typedef i32 FirstAndLastLine
173
174/**
175 *    INDENTED TITLE
176 * The text is less indented.
177 */
178typedef i32 IndentedTitle
179
180/**       First line indented.
181 * Unfortunately, this does not get indented.
182 */
183typedef i32 FirstLineIndent
184
185
186/**
187 * void code_in_comment() {
188 *   printf("hooray code!");
189 * }
190 */
191typedef i32 CodeInComment
192
193    /**
194     * Indented Docstring.
195     * This whole docstring is indented.
196     *   This line is indented further.
197     */
198typedef i32 IndentedDocstring
199
200/** Irregular docstring.
201 * We will have to punt
202  * on this thing */
203typedef i32 Irregular1
204
205/**
206 * note the space
207 * before these lines
208* but not this
209 * one
210 */
211typedef i32 Irregular2
212
213/**
214* Flush against
215* the left.
216*/
217typedef i32 Flush
218
219/**
220  No stars in this one.
221  It should still work fine, though.
222    Including indenting.
223    */
224typedef i32 NoStars
225
226/** Trailing whitespace
227Sloppy trailing whitespace
228is truncated.   */
229typedef i32 TrailingWhitespace
230
231/**
232 * This is a big one.
233 *
234 * We'll have some blank lines in it.
235 *
236 * void as_well_as(some code) {
237 *   puts("YEEHAW!");
238 * }
239 */
240typedef i32 BigDog
241
242/**
243*
244*
245*/
246typedef i32 TotallyDegenerate
247
248/**no room for newline here*/
249
250/* * / */
251typedef i32 TestFor3501a
252
253/**
254 * /
255 */
256typedef i32 TestFor3501b
257
258
259/* Comment-end tokens can of course have more than one asterisk */
260struct TestFor3709_00 { /* ? */ 1: i32 foo }
261/* Comment-end tokens can of course have more than one asterisk **/
262struct TestFor3709_01 { /* ? */ 1: i32 foo }
263/* Comment-end tokens can of course have more than one asterisk ***/
264struct TestFor3709_02 { /* ? */ 1: i32 foo }
265/** Comment-end tokens can of course have more than one asterisk */
266struct TestFor3709_03 { /* ? */ 1: i32 foo }
267/** Comment-end tokens can of course have more than one asterisk **/
268struct TestFor3709_04 { /* ? */ 1: i32 foo }
269/** Comment-end tokens can of course have more than one asterisk ***/
270struct TestFor3709_05 { /* ? */ 1: i32 foo }
271/*** Comment-end tokens can of course have more than one asterisk */
272struct TestFor3709_06 { /* ? */ 1: i32 foo }
273/*** Comment-end tokens can of course have more than one asterisk **/
274struct TestFor3709_07 { /* ? */ 1: i32 foo }
275/*** Comment-end tokens can of course have more than one asterisk ***/
276struct TestFor3709_08 { /* ? */ 1: i32 foo }
277
278struct TestFor3709 {
279  /** This is a comment */
280  1: required string id,
281  /** This is also a comment **/
282  2: required string typeId,
283  /** Yet another comment! */
284  3: required i32 endTimestamp
285}
286
287
288/* THE END */
289