Introduction to my new doc system

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.

Ddoc style macros delimit section divisions in just docs files

You can write under these sections and they will form a table of contents, with each one being linkable automatically.

Lower numbered headings will create sub-sections

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.

Let's talk about code.

I want to direct your attention to 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.

Linking

There's a few ways to link:

REF for referring to code names

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.

So, if you are documenting this code:

1 /** My class */
2 class Foo {
3    void method();
4    void method2();
5 }

And put a comment on method like see $(REF method2), it will know that refers to Foo.method2.

To link to something outside though, use the full name, including the package and module name, like std.stdio.File, even if you have already imported std.stdio in your module.

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 global module called stdio, without trying std.stdio first.

$(H4 LINK2 for External links

Phobos legacy macro compatibility

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.

Code highlighting

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:

---
This is highlighted as D code
---

This is highlighted as D code

For non-D code, program output, or other examples, you can use Markdown style `code` for inline code or

``` block code content ```.

block code content

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.

Lists, tables, and paragraphs

Paragraphs are exceedingly easy - just write ordinary text, with an empty line (or some other block) between them. The system will handle them automatically.

Lists and tables are currently only done with inline HTML. Yeah, I know, it isn't great.

Floating boxes

I like to have little boxes in my docs for tips, warnings, pitfalls

Special sections

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.

The list of sections are:

Params Returns Throws Lists exceptions the function may throw and their meanings. Diagnostics Lists common compiler errors you may see when trying to use this function

These may be reorganized by the doc processor.

ADR DOCS CODE FEATURES: * formatting of prototypes * linking of language features in prototypes * display of contracts * inheritance understanding * params and overloads documenting<F5>