Skip to content
Permalink
Browse files

update

  • Loading branch information
adamdruppe committed Mar 20, 2017
1 parent 8b9f718 commit 8cbb73c3078c7f02e88d39493f9efa7382b365a0
Showing with 8,565 additions and 83 deletions.
  1. +2 −2 Makefile
  2. +67 −1 adrdox_docs/syntax.d
  3. +1 −0 adrdox_docs/tips.d
  4. +1,321 −0 color.d
  5. +48 −16 comment.d
  6. +55 −36 doc2.d
  7. +231 −19 dom.d
  8. +2 −2 dub.json
  9. +2,270 −0 html.d
  10. +1,701 −0 jsvar.d
  11. +32 −5 locate.d
  12. +2,813 −0 script.d
  13. +22 −2 style.css
@@ -7,5 +7,5 @@ DSYMBOL_COMPONENTS=Dscanner/dsymbol/src/dsymbol/scope_.d Dscanner/dsymbol/src/ds

all:
#dmd diff.d terminal.d $(LIBDPARSE)
dmd -m64 doc2.d latex.d cgi.d comment.d stemmer.d dom.d -J. $(LIBDPARSE) -g # -debug=verbose
#dmd -of/var/www/dpldocs.info/locate locate.d dom stemmer.d cgi -J. -version=fastcgi -m64 -debug
dmd -m64 doc2.d latex.d cgi.d comment.d stemmer.d dom.d script.d jsvar.d html.d color.d -J. $(LIBDPARSE) -g # -debug=verbose
#dmd -of/var/www/dpldocs.info/locate locate.d dom.d stemmer.d cgi -J. -version=fastcgi -m64 -debug
@@ -177,7 +177,9 @@ $(CONSOLE
$(H3 Documented unittests)
I also implemented the feature from ddoc where unittests with a documentation comment are appended to the examples section of the previous documented declaration.
$(SIDEBAR Why does it allow inline examples? I often write full examples that I want to present in the prose, but I also like the compile check the unittests provide. So to get best of both worlds, I had to do it myself.)
I also implemented the feature from ddoc where unittests with a documentation comment are appended to the examples section of the previous documented declaration. They will appear in an `Examples` section (together with any others you manually write in `Examples:`), or inline in the documentation if you give them an `$(ID some_unique_name)` in the doc comment of the unittest, and write `$(EMBED_UNITTEST some_unique_name)` somewhere in your body text. Both the test and its associated comment will be moved to that location instead of being put in the examples section.
$(H2 Cross-referencing)
@@ -479,6 +481,70 @@ $(LIST
* `$(SUB subscript text)`
)
$(H3 Adding ID and class attributes to HTML)
You can add an ID or class attribute to an HTML tag by putting `$(ID id_here)` or `$(CLASS class_here)` inside a ddoc macro. It must be inside a `$(ddoc_style)` macro to be recognized.
$(H2 Ddoc Sections)
$(H3 List of supported DDoc Sections)
$(LIST
* `Examples:` or `Example:` gives usage examples. Documented unittests, if present and not embedded (see [#documented-unittests]), will also appear here.
* `Bugs:`
* `See_Also:`
* `Returns:`
* `Throws:`
* `Deprecated:`
* `Params:` uses a special `name = comment` syntax, just like ddoc, where only param names detected are printed.
* `Macros:` are read, but ignored.
)
$(H3 Meta subsections)
The following sections, if present, will be grouped under the `Meta` header:
$(LIST
* `Authors:` or `Author:`
* `Date`
* `License:`
* `Source:`
* `History:`
* `Credits:`
* `Standards:`
* `Copyright:`
* `Version:`
)
$(H3 Adrdox extension sections)
$(LIST
* `Diagnostics:` is a place to describe common errors you will see while trying to use the function, and explain how to fix them.
* `Link_References:` does name=value. See [#footnotes].
$(COMMENT * `Adrdox_Meta:` intrduces metadata for the generator. See [#metadata] )
)
$(H3 Custom sections)
If you start a line with `some_section:`, it will become a custom section in the document. It must have at least one underscore to be recognizes as a custom section.
$(COMMENT
$(H2 Metadata)
FIXME: NOT IMPLEMENTED
You can add metadata about your project to a `Adrdox_Meta:` section in the doc comment attached to the module declaration. These are inherited by submodules in your project as long as the package.d with the definition is loaded (see `--load` or passed as command line arg to be generated).
It can define:
$(LINK
* Project name
* Project logo image
* Project homepage
* Project color scheme: light or dark and accent color
* Scripts for the project
)
)
$(H2 Footnotes)
adrdox supports footnotes[1] and popup notes[2], scoped to the declaration attached to the comment. The syntax is to simply write `[n]`, such as `[1]`, where you want it to be displayed, then later in the comment, write a `Link_References:` section at the end of your comment, like so:
@@ -4,6 +4,7 @@ $(LIST
* Always have a package.d for your package, even if it contains no declarations.
* Always use a module declaration on all modules, and always put a comment on it.
* Always put a ddoc comment on a public decl, even if it is an empty comment.
* Want an index.html generated? Run adrdox on a `module index;` (this is a filthy hack but it works)
)
adrdox will not descend into undocumented entities, so a missing doc comment on a top level

0 comments on commit 8cbb73c

Please sign in to comment.
You can’t perform that action at this time.