1# Formatting Comments for Docs
2
3Documentation and example images are generated automatically from source code comments by the `scripts/docs_gen.py` script. Not all comments are added to the wiki. Just those comment blocks starting with certain keywords:
4
5- `// LibFile: NAME`
6- `// Section: NAME`
7- `// Module: NAME`
8- `// Function: NAME`
9- `// Constant: NAME`
10
11## LibFile:
12
13LibFile blocks can be followed by multiple lines that can be added as markdown text after the header. Indentation is important, as it denotes the end of block.
14
15```
16// LibFile: foo.scad
17// You can have several lines of markdown formatted text here.
18// You just need to make sure that each line is indented, with
19// at least three spaces after the comment marker. You can
20// denote a paragraph break with a comment line with three
21// trailing spaces.
22//
23// The end of the block is denoted by a line without a comment.
24```
25
26## Section:
27
28Section blocks can be followed by multiple lines that can be added as markdown text after the header. Indentation is important, as it denotes the end of block.
29
30Sections can also include Figures; images generated from code that is not shown in a code block.
31
32```
33// Section: Foobar
34// You can have several lines of markdown formatted text here.
35// You just need to make sure that each line is indented with
36// at least three spaces after the comment marker. You can
37// denote a paragraph break with a comment line with three
38// trailing spaces.
39//
40// The end of the block is denoted by a line without a comment,
41// or a line that is unindented after the comment.
42// Figure: Figure description
43// cylinder(h=100, d1=75, d2=50);
44// up(100) cylinder(h=100, d1=50, d2=75);
45// Figure(Spin): Animated figure that spins to show all faces.
46// cube([10,100,50], center=true);
47// cube([100,10,30], center=true);
48```
49
50## CommonCode:
51
52CommonCode blocks can be used to denote code that can be shared between all of the Figure and Example blocks in the file, without being shown itself. Indentation is important. Less than three spaces indent denotes the end of the block
53
54```
55// CommonCode:
56// module text3d(text, h=0.01, size=3) {
57// linear_extrude(height=h, convexity=10) {
58// text(text=text, size=size, valign="center", halign="center");
59// }
60// }
61```
62
63## Module:/Function:/Constant:
64
65Module, Function, and Constant docs blocks all have a similar specific format. Most sub-blocks are optional, except the Module/Function/Constant line, and the Description block.
66
67Valid sub-blocks are:
68
69- `Status: DEPRECATED, use blah instead.` - Optional, used to denote deprecation.
70- `Usage: Optional Usage Title` - Optional. Multiple allowed. Followed by an indented block of usage patterns. Optional arguments should be in braces like `[opt]`. Alternate args should be separated by a vertical bar like `r|d`.
71- `Description:` - Can be single-line or a multi-line block of the description.
72- `Arguments:` - Denotes start of an indented block of argument descriptions. Each line has the argument name, a space, an equals, another space, then the description for the argument all on one line. Like `arg = The argument description`. If you really need to explain an argument in longer form, explain it in the Description.
73- `Side Effects:` - Denotes the start of a block describing the side effects, such as `$special_var`s that are set.
74- `Example:` - Denotes the beginning of a multi-line example code block.
75- `Examples:` - Denotes the beginning of a block of examples, where each line will be shows as a separate example with a separate image if needed.
76
77Modules blocks will generate images for each example block. Function and Constant blocks will only generate images for example blocks if they have `2D` or `3D` tags. Example blocks can have tags added by putting then inside parentheses before the colon. Ie: `Examples(BigFlatSpin):`.
78
79The full set of optional example tags are:
80
81- `2D`: Orient camera in a top-down view for showing 2D objects.
82- `3D`: Orient camera in an oblique view for showing 3D objects. Used to force an Example sub-block to generate an image in Function and Constant blocks.
83- `Spin`: Animate camera orbit around the `[0,1,1]` axis to display all sides of an object.
84- `FlatSpin` : Animate camera orbit around the Z axis, above the XY plane.
85- `FR`: Force full rendering from OpenSCAD, instead of the normal preview.
86- `Small`: Make the image small sized.
87- `Med`: Make the image medium sized.
88- `Big`: Make the image big sized.
89
90Indentation is important, as it denotes the end of sub-block.
91
92```
93// Module: foo()
94// Status: DEPRECATED, use BLAH instead.
95// Usage: Optional Usage Description
96// foo(foo, bar, [qux]);
97// foo(bar, baz, [qux]);
98// Usage: Another Optional Usage Description
99// foo(foo, flee, flie, [qux])
100// Description: Short description.
101// Description:
102// A longer, multi-line description.
103// All description blocks are added together.
104// You _can_ use *markdown* notation as well.
105// You can end multi-line blocks by un-indenting the
106// next line, or by using a blank comment line like this:
107//
108// Arguments:
109// foo = This is the description of the foo argument. All on one line.
110// bar = This is the description of the bar argument. All on one line.
111// baz = This is the description of the baz argument. All on one line.
112// qux = This is the description of the qux argument. All on one line.
113// flee = This is the description of the flee argument. All on one line.
114// flie = This is the description of the flie argument. All on one line.
115// Side Effects:
116// `$floo` gets set to the floo value.
117// Examples: Each line below gets its own example block and image.
118// foo(foo="a", bar="b");
119// foo(foo="b", baz="c");
120// Example: Multi-line example.
121// lst = [
122// "multi-line examples",
123// "are shown in one block",
124// "with a single image.",
125// ];
126// foo(lst, 23, "blah");
127// Example(2D): Example to show as 2D top-down rendering.
128// foo(foo="b", baz="c", qux=true);
129// Example(Spin): Example orbiting the [0,1,1] axis.
130// foo(foo="b", baz="c", qux="full");
131// Example(FlatSpin): Example orbiting the Z axis from above.
132// foo(foo="b", baz="c", qux="full2");
133```
134
135
136