Worst Phobos documentation evar!

Mon Dec 29 22:04:41 PST 2014

On 30/12/2014 6:36 p.m., Andrei Alexandrescu wrote:
> On 12/29/14 9:13 PM, Rikki Cattermole wrote:
>> I wonder if I can get ddoc to generate json files.
>
> That should be possible (probably after a few improvements). I'm working
> on a few templates for alternate formats including LaTeX, plain text,
> and well, now json. -- Andrei

I've had a go, its mostly already possible for json.
Although escaping is a major issue. For things like a double quote.

This is what I have:

Ddoc

_=General macros for HTML generation. Even predefined macros are present
here for completeness. Macros defer wherever possible to style classes.

_=Simple tags, ordered alphabetically

A = $+
ADEF = $0
AHTTP = http://$1 $+
AHTTPS = https://$1 $+
ALOCAL = #$1$+
B = $0 $+
BIG = $0
BR =
CHECKMARK = ✔
DD = $0
DIV = $1 $+
DIVC = $1 $+
DIVCID = $1 $2 $3
DIVID = $1 $+
DL = $0
DOUBLEQUOTE = $(LDQUO)$0$(RDQUO)
DT = $0
ENUMERATE = [$(ITEMS_HELPER $1, $+)]
GREATER = >
ITEMIZE = [$(ITEMS_HELPER $1, $+)]
ITEMS_HELPER = "$1", $(ITEMS_HELPER $+)
FONT = $1 $+
H1 = $0
H2 = $0
H3 = $0
H4 = $0
H5 = $0
HR =
I = $0
LI = $0
LESS = <
OL = [$0]
P = $0
PRE = $0
SCRIPT = $0
SINGLEQUOTE = $(LSQUO)$0$(RSQUO)
SMALL = $0
SPAN = $1 $+
SPANC = $1 $+
SUBSCRIPT = $0
SUPERSCRIPT = $0
TABLE = $0
TABLEC = $1 $+
TD = $0
TD_HELPER = $(TD $1)$(TD_HELPER $+)
TH_HELPER = $(TH $1)$(TH_HELPER $+)
TR = $0
TT = $0
U = $0
UL = [$0]

_=Defining anchors and linking

LINK = $(A $0, $0)
LINK2 = $(A $1, $+)
HTTP = $(LINK2 http://$1,$2)
HTTPS = $(LINK2 https://$1,$2)
WEB = $(HTTP $1,$2)

_=Colors

COLOR = $(FONT color=$1, $+)
RED    = $0
GREEN  = $0
BLUE   = $0
YELLOW = $0
BLACK  = $0
WHITE  = $0

_=Explanatory stuff of the kind "Throws: blah" or "Returns:
blah". Note that if you want to make a SPAN-like (brief) explanation,
you can do it with the DIV block using "display: inline-block;", see
e.g. http://stackoverflow.com/questions/1611065/span-vs-div-inline-block

DDOC_EXPLANATORY=$(DIVC explanatory, $(SPANC explanation_item, $1:) 
$(DIVC $1, $+))

_=Predefined D-related stuff

D_CODE = $0
D_COMMENT = $(SPANC d_comment, $0)
D_STRING  = $(SPANC d_string, $0)
D_KEYWORD = $(SPANC d_keyword, $0)
D_PSYMBOL = $(SPANC d_psymbol, $0)
D_PARAM   = $(SPANC d_param, $0)

_=Main entry point

DDOC = {
	"Project": "$(TITLE)",
	$(BODY)
}

JSONVALUES = "$1", $(JSONVALUES $+)

_=DDoc-related stuff

DDOC_COMMENT   =
DDOC_DECL      = $(DT $(BIG $0))
DDOC_DECL_DD   = $(DD $0)
DDOC_DITTO     = $(BR)$0
DDOC_SECTIONS  = $0
DDOC_SUMMARY   = "Summary": "$0",
DDOC_DESCRIPTION = "Description:": "$0",
DDOC_AUTHORS   = "Authors:": [$(JSONVALUES $0)],
DDOC_BUGS      = "Bugs: "$0",
DDOC_COPYRIGHT = "Copyright": "$0",
DDOC_DATE      = "Date": $0",
DDOC_DEPRECATED = "Deprecated": "$0",
DDOC_EXAMPLES  = "Examples": "$0",
DDOC_HISTORY   = "History": "$0",
DDOC_LICENSE   = "License": "$0",
DDOC_RETURNS   = "Returns": [$0],
DDOC_SEE_ALSO  = "See Also": [$0],
DDOC_STANDARDS = "Standards": "$0",
DDOC_THROWS    = "Throws": "$0",
DDOC_VERSION   = "Version": "$0",
DDOC_SECTION_H = $0
DDOC_SECTION   = $0
DDOC_MEMBERS   = $0
DDOC_MODULE_MEMBERS   = $(DDOC_MEMBERS $0)
DDOC_CLASS_MEMBERS    = $(DDOC_MEMBERS $0)
DDOC_STRUCT_MEMBERS   = $(DDOC_MEMBERS $0)
DDOC_ENUM_MEMBERS     = $(DDOC_MEMBERS $0)
DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_PARAMS    = "Params": $0
DDOC_PARAM_ROW = $(TR $0)
DDOC_PARAM_ID  = $(TD $0)
DDOC_PARAM_DESC  = $(TD $0)
DDOC_BLANKLINE = $(BR)$(BR)

DDOC_ANCHOR  = $1
DDOC_PSYMBOL = $(U $0)
DDOC_KEYWORD = $(B $0)
DDOC_PARAM   = $(I $0)

_=HTML named entities, ordered approximately as in 
http://dlang.org/entity.html

QUOT = "
AMP = &

OELIG_CAP = Œ
OELIG = œ
SCARON_CAP = Š
SCARON = š
YUML = Ÿ
CIRC = ˆ
TILDE = ˜
ENSP =  
EMSP =  
THINSP =  
ZWNJ = ‌
ZWJ = ‍
LRM = ‎
RLM = ‏
NDASH = –
MDASH = —
LSQUO = ‘
RSQUO = ’
SBQUO = ‚
LDQUO = “
RDQUO = ”
BDQUO = „
DAGGER = †
DAGGER_CAP = ‡
PERMIL = ‰
LSAQUO = ‹
RSAQUO = ›
EURO = €
NBSP =  
IEXCL = ¡
CENT = ¢
POUND = £
CURREN = ¤
YEN = ¥
BRVBAR = ¦
SECT = §
UML = ¨
COPY = ©
REG = ®
ORDF = ª
LAQUO = «
NOT = ¬
SHY = 
REG = ®
MACR = ¯
DEG = °
PLUSMN = ±
SUP2 = &sup2;
SUP3 = &sup3;
ACUTE = ´
MICRO = µ
PARA = ¶
MIDDOT = ·
CEDIL = ¸
SUP1 = &sup1;
ORDM = º
RAQUO = »
FRAC14 = &frac14;
FRAC12 = &frac12;
FRAC34 = &frac34;
IQUEST = ¿
AGRAVE_CAP = À
AACUTE_CAP = Á
ACIRC_CAP = Â
ATILDE_CAP = Ã
AUML_CAP = Ä
ARING_CAP = Å
AELIG_CAP = Æ
CCEDIL_CAP = Ç
EGRAVE_CAP = È
EACUTE_CAP = É
ECIRC_CAP = Ê
EUML_CAP = Ë
IGRAVE_CAP = Ì
IACUTE_CAP = Í
ICIRC_CAP = Î
IUML_CAP = Ï
ETH_CAP = Ð
NTILDE_CAP = Ñ
OGRAVE_CAP = Ò
OACUTE_CAP = Ó
OCIRC_CAP = Ô
OTILDE_CAP = Õ
OUML_CAP = Ö
TIMES = ×
OSLASH_CAP = Ø
UGRAVE_CAP = Ù
UACUTE_CAP = Ú
UCIRC_CAP = Û
UUML_CAP = Ü
YACUTE_CAP = Ý
THORN_CAP = Þ
SZLIG = ß
AGRAVE = à
AACUTE = á
ACIRC = â
ATILDE = ã
AUML = ä
ARING = å
AELIG = æ
CCEDIL = ç
EGRAVE = è
EACUTE = é
ECIRC = ê
EUML = ë
IGRAVE = ì
IACUTE = í
ICIRC = î
IUML = ï
ETH = ð
NTILDE = ñ
OGRAVE = ò
OACUTE = ó
OCIRC = ô
OTILDE = õ
OUML = ö
DIVIDE = ÷
OSLASH = ø
UGRAVE = ù
UACUTE = ú
UCIRC = û
UUML = ü
YACUTE = ý
THORN = þ
YUML = ÿ
FNOF = ƒ
ALPHA_CAP = Α
BETA_CAP = Β
GAMMA_CAP = Γ
DELTA_CAP = Δ
EPSILON_CAP = Ε
ZETA_CAP = Ζ
ETA_CAP = Η
THETA_CAP = Θ
IOTA_CAP = Ι
KAPPA_CAP = Κ
LAMBDA_CAP = Λ
MU_CAP = Μ
NU_CAP = Ν
XI_CAP = Ξ
OMICRON_CAP = Ο
PI_CAP = Π
RHO_CAP = Ρ
SIGMA_CAP = Σ
TAU_CAP = Τ
UPSILON_CAP = Υ
PHI_CAP = Φ
CHI_CAP = Χ
PSI_CAP = Ψ
OMEGA_CAP = Ω
ALPHA = α
BETA = β
GAMMA = γ
DELTA = δ
EPSILON = ε
ZETA = ζ
ETA = η
THETA = θ
IOTA = ι
KAPPA = κ
LAMBDA = λ
MU = μ
NU = ν
XI = ξ
OMICRON = ο
PI = π
RHO = ρ
SIGMAF = ς
SIGMA = σ
TAU = τ
UPSILON = υ
PHI = φ
CHI = χ
PSI = ψ
OMEGA = ω
THETASYM = ϑ
UPSIH = ϒ
PIV = ϖ
BULL = •
HELLIP = …
PRIME = ′
PRIME = ″
OLINE = ‾
FRASL = ⁄
WEIERP = ℘
IMAGE = ℑ
REAL = ℜ
TRADE = ™
ALEFSYM = ℵ
LARR = ←
UARR = ↑
RARR = →
DARR = ↓
HARR = ↔
CRARR = ↵
LARR_CAP = ⇐
UARR_CAP = ⇑
RARR_CAP = ⇒
DARR_CAP = ⇓
HARR_CAP = ⇔
FORALL = ∀
PART = ∂
EXIST = ∃
EMPTY = ∅
NABLA = ∇
ISIN = ∈
NOTIN = ∉
NI = ∋
PROD = ∏
SUM = ∑
MINUS = −
LOWAST = ∗
RADIC = √
PROP = ∝
INFIN = ∞
ANG = ∠
AND = ∧
OR = ∨
CAP = ∩
CUP = ∪
INT = ∫
THERE4 = &there4;
SIM = ∼
CONG = ≅
ASYMP = ≈
NE = ≠
EQUIV = ≡
LE = ≤
GE = ≥
SUB = ⊂
SUP = ⊃
NSUB = ⊄
SUBE = ⊆
SUPE = ⊇
OPLUS = ⊕
OTIMES = ⊗
PERP = ⊥
SDOT = ⋅
LCEIL = ⌈
RCEIL = ⌉
LFLOOR = ⌊
RFLOOR = ⌋
LOZ = ◊
SPADES = ♠
CLUBS = ♣
HEARTS = ♥
DIAMS = ♦
LANG = ⟨
RANG = ⟩

Produces:

{
	"Project": "devisualization.window.interfaces.window",

"Summary": "Declared the majority of the interfaces for 
Devisualization.Window
",
"Authors:": ["Richard Andrew Cattermole
", ],
"License": "The MIT License (MIT)

		Copyright (c) 2014 Devisualization (Richard Andrew Cattermole)

		Permission is hereby granted, free of charge, to any person obtaining 
a copy
  		of this software and associated documentation files (the 
"Software"), to deal
  		in the Software without restriction, including without limitation 
the rights
  		to use, copy, modify, merge, publish, distribute, sublicense, and/or 
sell
  		copies of the Software, and to permit persons to whom the Software is
  		furnished to do so, subject to the following conditions:

  		The above copyright notice and this permission notice shall be 
included in all
  		copies or substantial portions of the Software.

  		THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
EXPRESS OR
  		IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  		FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 
SHALL THE
  		AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 
ARISING FROM,
  		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
DEALINGS IN THE
  		SOFTWARE.

",
"Examples": " 		To create a window without an OpenGL context:
Windowable d_psymbol window = d_keyword new Window(800, 600, d_string 
"My window!"w, 100, 100);
d_psymbol window.show();
Window.messageLoop();

  This runs the message loop after showing the window.
  Does nothing with events. Or show any content.",

WindowConfigstruct WindowConfig;

"Summary": "Arguments to create a window.
  Some may be optional.
",
"Description:": "A minimum width and height should be supplied.

",
"See Also": [Windowable],

WindowConfig.widthuint width;

"Summary": "Width of the window to create.
  Must be atleast 0 (px).",

WindowConfig.heightuint height;

"Summary": "Height of the window to create.
  Must be atleast 0 (px).",

WindowConfig.titlewstring title;

"Summary": "The title of the window to create.
  Commonly a UTF-8 support should be available.
      However if not ASCII will be used. Which is effectively a string.
      Assume ASCII values are safe as a value.
",
Default:
"A DWC window"

WindowConfig.xint x;

"Summary": "The x position of the window to be created.
  It is possible that this is ignored by the implementation.
",
Default:
0 (px)

WindowConfig.yint y;

"Summary": "The y position of the window to be created.
  It is possible that this is ignored by the implementation.
",
Default:
0 (px)

WindowConfig.contextTypeWindowContextType contextType;

"Summary": "Specifies the type of context to create. Validated by the 
window implementation.
",
Default:
None

Windowableinterface Windowable;

"Summary": "A generic window interface.
",
"Description:": " Should be supportive of majority of windowing toolkits 
in existance.
  Is unaware of screens.

  Implementation should support two constructors:
  d_keyword this(T...)(T config) { d_keyword this(WindowConfig(config)); }
  d_keyword this(WindowConfig config);

",
Events Mechanism:
  		A window support a set number of events.
		From those the event offer set functionality to manipulate them.

   Adds a listener on an event
	d_keyword void addEventName(d_keyword void d_keyword delegate(T));
	d_keyword void addEventName(d_keyword bool d_keyword delegate(T));

	Removes the provided listener
	d_keyword void removeEventName(d_keyword bool d_keyword delegate(T));
	d_keyword void removeEventName(d_keyword void d_keyword delegate(T));

	Counts how many listeners for an event
	size_t countEventName();

	Runs the event for all listeners with the given arguments
	d_keyword void eventName(T);

	Clears all listeners for an event
	d_keyword void clearEventName();

	Optionally will also support:
	d_keyword void eventName(T[1 .. $]);

	Where T[0] is Windowable.
	This will run the event and pass in as first argument this (Windowable).

Events:
Upon the message loop drawing period this is called.<br/>
   onDraw		=	Windowable

   When the message loop is informed the window has moved, this is 
called.<br/>
   onMove		=	Windowable, int x, int y

  	When the message loop is informed the window has resized, this is 
called.<br/>
  	onResize	=	Windowable, uint newWidth, uint newHeight

   When the window has been requested to be closed from the user, this 
is called.<br/>
   On this event Windowable.close must be called manually.<br/>
   onClose		=	Windowable

Windowable.messageLoopstatic void messageLoop();

"Summary": "Continues iteration of the message loop.
",
"Description:": "This is expected functionality provided from the 
implementation.",

Windowable.messageLoopIterationstatic void messageLoopIteration();

"Summary": "A single iteration of the message loop.
",
"Description:": "This is expected functionality provided from the 
implementation.",

Windowable.showabstract void show();

"Summary": "Hides the window.
",
"See Also": [hide],

Windowable.hideabstract void hide();

"Summary": "Shows the window.
",
"See Also": [close],

Windowable.titleabstract @property void title(string text);

"Summary": "Sets the title text.
",
"Params": string text
The text to set the title of the window to

Windowable.titleabstract @property void title(dstring text);

"Summary": "Sets the title text.
",
"Params": dstring text
The text to set the title of the window to

Windowable.titleabstract @property void title(wstring text);

"Summary": "Sets the title text.
",
"Params": wstring text
The text to set the title of the window to

Windowable.sizeabstract @property void size(uint width, uint height);

"Summary": "Resize the window.
",
"Description:": "Does not animate.

",
"Params": uint width
The width to set to
uint height
The height to set to

Windowable.moveabstract @property void move(int x, int y);

"Summary": "Move the window to coordinate.
",
"Description:": "Coordinate system based upon Top left corner of screen.
  Does not support screens (could be moved outside main screen).
  Coordinates can be negative, but is dependent upon the OS.

",
"Params": int x
The x coordinate to move to
int y
The y coordinate to move to

Windowable.canResizeabstract @property void canResize(bool can = true);

"Summary": "Enable / disable resizing of the window.
",
"Params": bool can
Is it possible to resize the window (default yes)

Windowable.fullscreenabstract @property void fullscreen(bool 
isFullscreen = true);

"Summary": "Go into/out fullscreen
",
"Params": bool isFullscreen
Should be fullscreen (default yes)

Windowable.closeabstract @property void close();

"Summary": "Closes the window.
  The window cannot reopened once closed.
",
"See Also": [hide],

Windowable.hasBeenClosedabstract @property bool hasBeenClosed();

"Summary": "Has the window been closed?
",
"Returns": [True if close has been called

],
"See Also": [close],

Windowable.contextabstract @property IContext context();

"Summary": "Gets the current context that the window has open or null 
for none.
",
"Returns": [A context that has a buffer that can be swapped and 
activated once created],

Windowable.iconabstract void icon(Image image);

"Summary": "Sets the icon for the window.
  Supports transparency.
",
"Params": Image image
The image (from Devisualization.Image).

Windowable.icondeprecated abstract void icon(ushort width, ushort 
height, ubyte[3][] data, ubyte[3]* transparent = null);

"Summary": "Sets the icon for the window.
  Supports transparency.
",
"Params": ushort width
The width of the icon
ushort height
The height of the icon
ubyte[3][] data
rgb data 0 .. 255, 3 bytes per pixel
ubyte[3]* transparent
The given pixel (3 bytes like data) color to use as transparency

"Deprecated": "Superseded by using Devisualization.Image's Image, as 
argument instead.",

}

Pretty yucky in terms of whitespace.