1 // just docs: Introduction to my new doc system
2 /++
3 
4 This is a one-line summary of the doc that can be used in tooltips.
5 
6 This elaboration is still part of the short synopsis and will show up in the table of contents. You can put a few paragraphs there.
7 
8 When you are ready to get into details, enter two blank lines.
9 
10 
11 We are now into the details. The doc system will automatically insert stuff like a table of contents, function prototype, etc. at the gap. You will only see this stuff if you actually go to the doc's page itself.
12 
13 $(H2 Ddoc style macros delimit section divisions in just docs files)
14 
15 You can write under these sections and they will form a table of contents, with each one being linkable automatically.
16 
17 $(H3 Lower numbered headings will create sub-sections)
18 
19 Like in HTML, you have the different header levels to nest sections. Just write a new heading and it will handle the rest for you.
20 
21 $(H2 Let's talk about code.)
22 
23 I want to direct your attention to $(REF std.file.dirEntries). Making references to other items is as simple wrapping a name in `$(REF ...)`. The system will do a lookup for you. You can even reference other articles since they, too, have module names.
24 
25 $(H3 Linking)
26 
27 There's a few ways to link:
28 
29 $(H4 REF for referring to code names)
30 
31 REF means look up the name in the module's symbol table and link to it. It does NOT process imports because readers of your documentation don't know what imports you've used, but it DOES walk up the local scope tree.
32 
33 So, if you are documenting this code:
34 
35 ---
36 /** My class */
37 class Foo {
38    void method();
39    void method2();
40 }
41 ---
42 
43 And put a comment on `method` like `see $(REF method2)`, it will know that refers to `Foo.method2`.
44 
45 To link to something outside though, use the full name, including the package and module name, like $(REF std.stdio.File), even if you have already imported std.stdio in your module.
46 
47 The doc processor assumes that any name it cannot locate locally is a full name. It does not attempt to process the same package before going global, so `$(REF stdio)` in `std.file` will refer to a $(I global) module called `stdio`, without trying `std.stdio` first.
48 
49 $(H4 LINK2 for External links
50 
51 $(H4 Phobos legacy macro compatibility)
52 
53 A few of the Phobos legacy macros still work, but should not be used unless you specifically need ddoc compatibility. Instead, just use the generic REF.
54 
55 
56 $(H3 Code highlighting)
57 
58 There's ways to do both inline and block level D examples in the comment. Inline D code is wrapped in `$(D this is a bit of code)`. This runs the syntax highlighter on that tiny snippet inline. For a block of D example, you can bracket it in `---`, just like Ddoc of old:
59 
60 ```
61 ---
62 This is highlighted as D code
63 ---
64 ```
65 
66 ---
67 This is highlighted as D code
68 ---
69 
70 
71 For non-D code, program output, or other examples, you can use Markdown style $(BACKTICK)code$(BACKTICK) for inline code or
72 
73 $(BACKTICK)$(BACKTICK)$(BACKTICK)
74 block code content
75 $(BACKTICK)$(BACKTICK)$(BACKTICK).
76 
77 ```
78 block code content
79 ```
80 
81 These options work the same way, except they don't syntax highlight D keywords. In the three-ticks code block, you can specify a language. This doc generator ignores that right now, except of `dmd`, which it takes to mean it is a message from the compiler.
82 
83 $(H2 Lists, tables, and paragraphs)
84 
85 Paragraphs are exceedingly easy - just write ordinary text, with an empty line (or some other block) between them. The system will handle them automatically.
86 
87 Lists and tables are currently only done with inline HTML. Yeah, I know, it isn't great.
88 
89 $(H2 Floating boxes)
90 
91 I like to have little boxes in my docs for tips, warnings, pitfalls
92 
93 $(H2 Special sections)
94 
95 Like Ddoc, I parse for a few special sections. Any line that starts with `Section:`, where Section is a list of pre-defined sections, can start a new one.
96 
97 The list of sections are:
98 
99 	Params
100 	Returns
101 	Throws
102 		Lists exceptions the function may throw and their meanings.
103 	Diagnostics
104 		Lists common compiler errors you may see when trying to use this function
105 
106 These may be reorganized by the doc processor.
107 
108 
109 ADR DOCS CODE FEATURES:
110 	* formatting of prototypes
111 	* linking of language features in prototypes
112 	* display of contracts
113 	* inheritance understanding
114 	* params and overloads documenting<F5>
115 
116 +/
117 module arsd.docs.adrdoc.intro;
118 
119 /++
120 	This is a complete example that can be compiled and run as part of
121 	the documentation. This text along with the source code in the
122 	unittest block below will be added into the documentation page.
123 +/
124 unittest {
125 	import arsd.cgi;
126 
127 	void hello(Cgi cgi) {
128 		cgi.write("Hello!");
129 	}
130 
131 	mixin GenericMain!hello;
132 }
Suggestion Box / Bug Report