dlang/ddox

Advanced D documentation engine

ddox's Issues

Can't build ddox

I'm getting different symptoms from #53, so making this a separate ticket.

Using the current ddox master, with both DMD 2.065.0 and 2.064.2, and compiling ddox using dub build I get:

source\ddox\htmlgenerator.d(209): Error: undefined identifier StreamOutputRange

And with DMD 2.066.0 I get:

rsertools.d(12): Error: module metastrings is in file 'std\metastrings.d' which
cannot be read```

Templates showing up under templates, global variables and aliases

No idea why this happens..

This one shows under templates and aliases:

template isValue(T)
{
    enum isValue = !is(T);
}

template isValue(alias T)
{
    enum isValue = !is(T);
}

And this under templates and global variables:

template isEqual(alias A, alias B)
{
    static if( isValue!A && isValue!B && __traits(compiles, A == B))
        enum isEqual = A == B;
    else static if(!(isValue!A || isValue!B))
        enum isEqual = isSameType!(A, B);
    else
        enum isEqual = false;
}
/// ditto
template isEqual(alias A, B)
{
    enum isEqual = false;
}
/// ditto
template isEqual(A, alias B)
{
    enum isEqual = false;
}
/// ditto
template isEqual(A, B)
{
    enum isEqual = isSameType!(A, B);
}

templates doesn't show properly

The following simple templates:

/// Returns:
///     true if T is a symbol or literal
/// Params:
///     T = Type or symbol
template isSymbol(T)
{
    enum isSymbol = !is(T);
}
/// ditto
template isSymbol(alias T)
{
    enum isSymbol = !is(T);
}

Is rendered by ddox as:

module traits;

// ...
void isSymbol!(alias T);
// ...

So it only shows the last overload, and for some reason insists it's void

Errors generating

I've stripped away many similar entries.

Parsing docs...
[7F706C55C070:00000000 ERR] Expected function type for '', got Primitive
(...)
[7F706C55C070:00000000 ERR] Error parsing type 'U[1 .. __dollar]': Expected ']', got '..'.
[7F706C55C070:00000000 ERR] Expected function type for '', got Primitive
(...)
Finished parsing docs.

UDAs doesn't show in the documentation

struct UDA {}
@UDA enum E {}

Es documentation doesn't show UDA anywhere.

What's {null}?

enum E {
  v1 = 1
}

What's the {null} left of v1?

Incorrect function prototypes generated

Looking at the phobos ddox documentation,
http://vibed.org/temp/d-programming-language.org/phobos/std/array/assocArray.html

In the prototype, for assocArray, you will see:

assocArray(Range)(
  RedBlackTree.Range r
) auto;

The Range parameter shouldn't be RedBlackTree.Range. This can be noticed in other pages too.
Also, auto seems misplaced.

sitemap.xml shows absolute path in <loc>

I haven't read the sitemap specification, but is the full path supposed to be added?

<url>
  <loc>http://localhost:8080/index.html</loc>
</url>

Strings aren't escaped in file names

For example, I have a mixin called Property that takes 3 string arguments, and ddox produces this error:

 Failed to open file 'path\to\file\Component.Property!("GameObject", "owner", "public").html'.

This is happening on Windows.

errors compiling with dmd 2.060 64-bit on Linux

v0.9.3 properly compiles, but with v0.9.4 and the current trunk, I got these errors:

source/ddox/ddoc.d(93): Error: not a property lines[cast(ulong)i..cast(ulong)j].map!(__lambda30)
source/ddox/ddoc.d(34): Error: template instance ddox.ddoc.filterDdocComment!(Appender!(string)) error instantiating

BTW, I would like to thank you for this yet another wonderful project :-)

[enh] Documented unittest as the default

This:

/**                                                                                                                                                                             
 * Test function.                                                                                                                                                               
 */
bool    test() { return true; }

/**                                                                                                                                                                             
   What the heck ?                                                                                                                                                              
 */
unittest
{
    assert(test());
}

Procuce this:

by default.

IMHO, if someone documents an unittest, he would expect it to be showed out of the box (which is also DDoc behavior).
I understand that one may want to keep one's unittests undocumented publicly, but IMHO it is the exception rather than the default.

So could we switch from "--unittest-examples" to something like "--strip-documented-unittest" ?

Note: The new phobos layout currently lacks tons of examples.
Ie: old version of bringToFront vs new version.of bringToFront

Build error in ddox/parsers/dparse

Building ddox master with dub fails with
source/ddox/parsers/dparse.d(275): Error: function vibe.data.serialization.name (string name) is not callable using argument types (AliasDeclaration)

DMD 2.066.1

kind: "mixin" unsupported

In JsonParser ln: 138. The following makes the documentation generate correctly:
default: return null; // enforce(false, "Unknown declaration kind: "~json.kind.get!string); assert(false);

Maybe outputting a warning, instead of failing to generate documentation would be applicable?

[0.9.14] Warns about stray ')' in comment in example block

I have code like this

/++
Example

---
// Comment with (

---
+/

Warning: Ddoc: Stray ')'. This may cause incorrect Ddoc output. Use $(RPAREN) instead for unpaired right parentheses

Enum values ends in ;

enum E {
  v1 = 1
}

The documentation shows this as

enum E
{
    // ...
    {null} v1;
    // ...
}

Shouldn't comma be used instead of semicolon?

Value template paramter types isn't linked.

void f(SomeType v)(OtherType v)

Only OtherType will be a clickable link, not SomeType

Templates cannot be documented ?

Maybe the JSON output changed. The name field is just the name, but it looks like ddox expects name(args) there.

size_t in code shows up as uint

In code, my constructor looks like this:

this(size_t peerCount,
     size_t channelLimit,
     uint incomingBandwidth=0,
     uint outgoingBandwidth=0)

In the ddox documentation for the constructor, it shows up as:

this(
  uint peerCount,
  uint channelLimit,
  uint incomingBandwidth,
  uint outgoingBandwidth
);

Notice that size_t => uint which may be true for my particular system, but maybe not others.

Private undocumented templates is showing in the documentation

module app;
private template t() {} // oops - documented
void main() {}

Is GDC output supported?

For whatever reason, DMD crashes when running -X -Xf(stuff) flags on my code, so I've been trying to shove GDC output into DDOX, only to find that then DDOX crashes with exceptions. My question is thus: Is GDC supported?

If it isn't, I won't bother you with whatever crashing issues I'm having with DDOX. :-)

EDIT: I take it back. It was just a problem DDOX was having with mixins. Changed my code into something more readable and it serve-htmled properly (although for whatever reason generate-html is broken...). Closing!

EDIT EDIT: I take back the 'broken' bit. Everything's fine. I'm just a fool. >.<

Unittests are showing in the documentation

Stuff like this crops up:

__unittestL24_1 
__unittestL71_3

Modules without module definition isn't generated

Not sure if this worth looking into as every module would probably have a definition in practice.

To reproduce: dub init, document some function in app.d, run ddox.
app.d isn't generated. Including module app; at the top fixes the problem.

Function overloads is listed several times in the module doc

.. It's correctly grouped when looking at the function, but in the module it's listed once per overload:

Functions
Name    Description
getDoc  
getDoc  
getDoc

Function getDoc

Overload group

typeof(null) parameters are omitted

uncaught exception originating from vibe/data/json.d(253) for class with inner mixin template

I encountered this error when using mixin templates and boiled it down to the following files:

tmp.d: http://pastebin.com/E6bVrt5R
tmp.json: http://pastebin.com/hnbpfmVh
Error: http://pastebin.com/MY18YiCn

DDOX version: 0.9.14
vibe version: whichever one was provided by dub Oct 28 of this year.
DMD version: 2.063.2

tl;dr: Hard error using DDOX on D file with inner mixin templates, originating from somewhere in vibe's json.d file.

Various search improvement suggestions

• Support abbreviation matching (e.g. "fqn" matches "fullyQualifiedName")
• Automatically hide the search result bubble when the search box doesn't have the focus
• Support up/down + enter navigation for the search result list
• Keep the search box text when going to a result page

templates showing void type

code:

/// doc
template test()
{
    enum test = true;
}

ddox:

Name    Type    Description
test     void   doc

Line doc comments handled wrong (DMD issue?)

I'm not sure if this is an issue with ddox or dmd, but doc comments like this are handled wrong, which is a bit of a pain:

/// This function is here to aid in making your
/// software do cool stuff.
void foo() {}

ddox splits that into two ugly paragraphs:

This function is here to aid in making your

software do cool stuff.

Instead of:

This function is here to aid in making your software do cool stuff.

ddox doesn't read package.json for info

Two things:

1. API documentation main page doesn't show author, copyright and license from package.json
2. Modules missing author++ info isn't read from package.json

Not sure if 2) should be fixed, but 1) would be great.

Add better `ddox` description in the `README.md` file

Please, add answer to the main question: "Why should I use this program?". So, please add a list of main benefits/features of ddox and describe why is better than DMD's DDOC engine.

Add the possibility to inject override/default macros when generating docs

Currently setDefaultDdocMacroFiles and setOverrideDdocMacroFiles is the only possibility to do this, but those are global settings. DocGroupContext would be the ideal place to pass this information per generator.

See also http://forum.dlang.org/post/[email protected]

Disqus login doesn't work

Just tried to comment on http://vibed.org/temp/dlang.org/library/index.html.
Not sure if this is disabled deliberately and if it would be possible to keep the comments once the documentation is on http://dlang.org.

Doesn't understand ```.f``` to be global scope

If you have a member called f, this member is linked in the documentation rather than the global.

Template constraints are not included in documentation

Knowing the template constraints is important for properly documenting many template-heavy APIs.

I have some proof-of-concept changes on a fork.

Implementing this will require that dlang/dmd#3657 is merged into DMD.

ddox fails to build due to vibe.d

When trying to install and build the latest version of ddox this fails due to errors in the vibe.d source code:

$ dub install ddox
$ dub build ddox
Checking dependencies in '/home/yorickpeterse/.dub/packages/ddox-0.9.14'
Building configuration "application", build type debug
Compiling...
../vibe-d-master/source/vibe/data/bson.d(1235): Error: function declaration without return type. (Note that constructors are always named 'this')
../vibe-d-master/source/vibe/data/bson.d(1235): Error: no identifier for declarator isSupportedValueType(T)
../vibe-d-master/source/vibe/data/bson.d(1235): Error: semicolon expected following function declaration
../vibe-d-master/source/vibe/data/bson.d(1235): Error: Declaration expected, not '='
../vibe-d-master/source/vibe/data/serialization.d(343): Error: unexpected ( in declarator
../vibe-d-master/source/vibe/data/serialization.d(343): Error: basic type expected, not alias
../vibe-d-master/source/vibe/data/serialization.d(343): Error: found 'alias' when expecting ')'
../vibe-d-master/source/vibe/data/serialization.d(343): Error: no identifier for declarator hasAttribute(int)
../vibe-d-master/source/vibe/data/serialization.d(343): Error: semicolon expected following function declaration
../vibe-d-master/source/vibe/data/serialization.d(343): Error: no identifier for declarator decl
../vibe-d-master/source/vibe/data/serialization.d(343): Error: semicolon expected, not ')'
../vibe-d-master/source/vibe/data/serialization.d(343): Error: Declaration expected, not ')'
../vibe-d-master/source/vibe/data/json.d(1180): Error: function declaration without return type. (Note that constructors are always named 'this')
../vibe-d-master/source/vibe/data/json.d(1180): Error: no identifier for declarator isJsonBasicType(T)
../vibe-d-master/source/vibe/data/json.d(1180): Error: semicolon expected following function declaration
../vibe-d-master/source/vibe/data/json.d(1180): Error: Declaration expected, not '='
../vibe-d-master/source/vibe/data/json.d(1182): Error: function declaration without return type. (Note that constructors are always named 'this')
../vibe-d-master/source/vibe/data/json.d(1182): Error: no identifier for declarator isSupportedValueType(T)
../vibe-d-master/source/vibe/data/json.d(1182): Error: semicolon expected following function declaration
../vibe-d-master/source/vibe/data/json.d(1182): Error: Declaration expected, not '='
../vibe-d-master/source/vibe/data/json.d(1261): Error: function declaration without return type. (Note that constructors are always named 'this')
Error: DMD compile run failed with exit code 1

Run 'dub help' for usage information.

Don't inherit constructors

Currently this methods of classes are erroneously inherited in the documentation. They should be completely excluded from that process.

Catch-22 when using ')' in code examples.

Take this example of an example in DDoc:

 * Example:
 * ---
 * // Find an '$(RPAREN)' in a buffer of 1024 bytes using an additional sentinel.
 * size_t length = 1024;
 * char[] buffer = new char[](length+1);
 * buffer[length] = '$(RPAREN)';
 * auto pos = buffer.ptr.find!('$(RPAREN)');
 * if (pos < length) { // was an actual find before the sentinel }
 * ---

I had to use $(RPAREN) to silence DDox warnings about probably incorrect output for unmatched right parenthesis only to be warned that the character literal isn't terminated. In other words something expects '$' and cannot handle marcos that expand to a single character.

`@property @property` appears twice in function signature

Just found this in the vibe.d docs but I guess it is a ddox bug.

GDC's 'type' in JSON file for extern(C) function returning pointer confuses DDOX

Here's a file: http://pastebin.com/Fc0yS7Mr

Running dmd -X main.d and subsequently calling ddox generate-html main.json doc works to completion.

Running dmd -fXf=main.json main.d and subsequently calling ddox generate-html main.json doc causes this failure: Expected function type for 'a*C ()'/'', got Pointer

Given that the type field isn't even populated by the DMD JSON output, I'm not quite sure if this is a problem in GDC or in DDOX.

I've paste-binned the generated JSONs for GDC (http://pastebin.com/4JVQrybk) and DMD (http://pastebin.com/EfAbY1s6).

EDIT: A cursory glance over some other errors I'm getting suggests that DDOX has some trouble parsing function types with attributes.

Enum values doesn't show in the documentation

enum E {
  v1 = 1
}

1 doesn't show for v1

Compilation error with DMD head - Switch case fall-through.

On line 1064 of ddox/internal/demangle.d, the implicit fall through will fail to compile with DMD head. Instead it would need to be changed to explicitly use goto case '0' to fall through to case '0' .. '9'.

Build Log:
dub --build=ddox
snipped
Compiling...
Compiling diet template 'ddox.overview.dt' (compat)...
Compiling diet template 'ddox.module.dt' (compat)...
Compiling diet template 'ddox.variable.dt' (compat)...
Compiling diet template 'ddox.function.dt' (compat)...
Compiling diet template 'ddox.composite.dt' (compat)...
Compiling diet template 'ddox.template.dt' (compat)...
Compiling diet template 'ddox.enum.dt' (compat)...
../../.dub/packages/ddox-0.9.17/source/ddox/internal/demangle.d(1064): Error: switch case fallthrough - use 'goto case;' if intended
Error executing command run: DMD compile run failed with exit code 1

default argument values not shown

In code, my constructor looks like this:

this(size_t peerCount,
     size_t channelLimit,
     uint incomingBandwidth=0,
     uint outgoingBandwidth=0)

In the ddox documentation for the constructor, it shows up as:

this(
  uint peerCount,
  uint channelLimit,
  uint incomingBandwidth,
  uint outgoingBandwidth
);

It would be useful if the ddox documentation showed the default values for incomingBandwidth and outgoingBandwidth.

Build failure with dmd 2.066

ddox pulls in vibe v0.7.20, which fails to build on dmd 2.066. After tweaking package.json so that it uses the master branch of vibe ("vibe-d": "~master"), we are met with the following:

Compiling diet template 'ddox.overview.dt' (compat)...
/usr/include/dlang/dmd/core/stdc/stdarg.d(215): Error: 'std.variant.VariantN!32LU.VariantN.opAssign!(VariantN!32LU).opAssign' is not nothrow
/usr/include/dlang/dmd/core/stdc/stdarg.d(205): Error: function 'core.stdc.stdarg.va_arg!(VariantN!32LU).va_arg' is nothrow yet may throw
/usr/include/dlang/dmd/core/stdc/stdarg.d(201): Error: template instance core.stdc.stdarg.va_arg!(VariantN!32LU) error instantiating
../.dub/packages/vibe-d-master/source/vibe/templ/diet.d-mixin-105(107):        instantiated from here: va_arg!(VariantN!32LU)
../.dub/packages/vibe-d-master/source/vibe/templ/diet.d(93):        instantiated from here: compileDietFileCompatV!("ddox.overview.dt", HTTPServerRequest, "req", DocPageInfo, "info")
source/ddox/htmlgenerator.d(249):        instantiated from here: compileDietFileCompat!("ddox.overview.dt", HTTPServerRequest, "req", DocPageInfo, "info")

Template specializations isn't included

.. so my documentation looks like this:

T consume(T, ubyte N)(
  ref ubyte[] packet
) pure nothrow;

T consume(T, ubyte N)(
  ref ubyte[] packet
) pure nothrow;

Variables that might be excluded by static if isn't documented

/// doc for S
struct S(bool b) {
    static if(b)
        int i; /// doc for i
}

Documentation for i isn't generated.
ddoc gets this right (although S must be documented: http://d.puremagic.com/issues/show_bug.cgi?id=9719 unlike ddox)

Functions separated by unittest isn't grouped correctly.

code:

/// doc
string f()(int i) {}
unittest {}
/// ditto
void f(T)() {}

ddox:

Name    Description
f   doc
f   

Notice that the ///ditto documentation doesn't work either.

@property is marked as [set] even though it is clearly a getter

Hello, in my code I have something like this:

...
/// Gets data.
ubyte[] data() @property
{
    return _classInstanceVariable;
}

/**
 * Sets data.
 * Throws: ProjectException if dirty
 */
void data(ubyte[] data) @property
{
    if(!_dirty)
    {
        _classInstanceVariable = data;
    }
    else
    {
        throw new ProjectException("cannot set when dirty");
    }
}
...

ddox marks the first function as [set] with a type of {null}. I'm expecting that it should mark it as [get]. Is there a way to explicitly mark it?

Author documentation sytax - WAS: < and > in ddoc isn't escaped

.. at least in Authors blocks. Not sure if this is intended to easier embed html though.

Authors:
My Name <[email protected]>

Is added as:

<p>My Name <[email protected]></p>

Perhaps even this could be fixed to:

<p>My Name &lt;<a href="mailto:[email protected]">[email protected]</a>&gt;</p>

Probably involves a hack, but it's a common way to write author info (using RCPT TO syntax).

[0.9.14] Multiple _ in documentation is replaced with a single _

I has comment like this
/// __something
and in ddox it became _something

[0.9.13] Errors calling both vibe and phobos

..\..\..\ProgramData\dub\packages\ddox-0.9.13\source\ddox\htmlgenerator.d(162): Error: function vibe.core.stream.OutputStream.write (const(ubyte[]) bytes) is not callable using argument types (string, bool)
..\..\..\ProgramData\dub\packages\ddox-0.9.13\source\ddox\htmlgenerator.d(163): Error: function vibe.core.stream.OutputStream.write (const(ubyte[]) bytes) is not callable using argument types (string, bool)
..\..\..\ProgramData\dub\packages\ddox-0.9.13\source\ddox\htmlgenerator.d(166): Error: function vibe.core.stream.OutputStream.write (const(ubyte[]) bytes) is not callable using argument types (string, bool)
..\..\..\ProgramData\dub\packages\ddox-0.9.13\source\ddox\htmlgenerator.d(168): Error: function vibe.core.stream.OutputStream.write (const(ubyte[]) bytes) is not callable using argument types (string, bool)
..\..\..\ProgramData\dub\packages\ddox-0.9.13\source\ddox\htmlgenerator.d(169): Error: function vibe.core.stream.OutputStream.write (const(ubyte[]) bytes) is not callable using argument types (string, bool)
Compiling diet template 'ddox.overview.dt' (compat)...
Compiling diet template 'ddox.module.dt' (compat)...
Compiling diet template 'ddox.variable.dt' (compat)...
Compiling diet template 'ddox.function.dt' (compat)...
Compiling diet template 'ddox.composite.dt' (compat)...
Compiling diet template 'ddox.template.dt' (compat)...
Compiling diet template 'ddox.enum.dt' (compat)...
C:\dmd\windows\bin\..\..\src\phobos\std\traits.d(5557): Error: static assert  "Type ulong does not have an Unsigned counterpart"
C:\dmd\windows\bin\..\..\src\phobos\std\traits.d(5420):        instantiated from here: Modifier!(ulong)
C:\dmd\windows\bin\..\..\src\phobos\std\traits.d(5561):        instantiated from here: ModifyTypePreservingSTC!(Impl, ulong)
C:\dmd\windows\bin\..\..\src\phobos\std\bitmanip.d(1445):        instantiated from here: Unsigned!(ulong)
C:\dmd\windows\bin\..\..\src\phobos\std\bitmanip.d(1715):        ... (1 instantiations, -v to show) ...
C:\dmd\windows\bin\..\..\src\phobos\std\bitmanip.d(1692):        instantiated from here: bigEndianToNativeImpl!(ulong, 8u)
..\..\..\Users\simen\AppData\Roaming\dub\packages\vibe-d-master\source\vibe\http\websockets.d(399):        instantiated from here: bigEndianToNative!(ulong, 8u)