-D option = Embedded documentation

Dec 16, 2011

dune

Dec 16, 2011

Trass3r

Dec 16, 2011

Dec 16, 2011

Dec 16, 2011

Dec 16, 2011

Dec 16, 2011

Dec 16, 2011

Never tried this before: Tried (with D2.057) to use the embedded documentation option with: /** * documentation here */ and the html files are generated but they only contain a html skeleton and no documentation. Any hints?

Am 16.12.2011, 17:47 Uhr, schrieb dune <do-not@email.com>: > Never tried this before: > > Tried (with D2.057) to use the embedded documentation option with: > > /** > * documentation here > */ > > and the html files are generated but they only contain a html skeleton and no documentation. This comment doesn't refer to any code.

December 16, 2011

Re: -D option = Embedded documentation

Posted by Timon Gehr
in reply to dune

Permalink

Timon Gehr

Posted in reply to dune

Permalink

On 12/16/2011 06:12 PM, dune wrote:
> What?
>
> Sorry but I don't understand...
>
> What I posted was an example, in reality there is tons of code inside the d file.
>
> Thanks

That is not what you said. Obviously you should always give an example that actually fails, especially when you claim it does.

$ cat worksforme.d
/**
 * documentation here
 */
module worksforme;

/// program entry point
void main(){}

$ dmd -D worksforme
$ cat worksforme.html
<html><head>
        <META http-equiv="content-type" content="text/html; charset=utf-8">
        <title>worksforme</title>
        </head><body>
        <h1>worksforme</h1>
        <!-- Generated by Ddoc from worksforme.d -->
documentation here<br><br>

<dl><dt><big>void <u>main</u>();
</big></dt>
<dd>program entry point<br><br>

</dd>
</dl>

        <hr><small>Page generated by <a href="http://www.digitalmars.com/d/2.0/ddoc.html">Ddoc</a>. </small>
        </body></html>

I didn't realize that stuff like this will not work as expected: [code] /*********************************** * Brief summary of what * myfunc does, forming the summary section. * * First paragraph of synopsis description. * * Second paragraph of * synopsis description. */ void myfunc() { } /*********************************** * This is just some text that * should be added to the * documentation */ // below is the next chunk of code [/code] The second block of documentation will not show up. Here the section of the D2 DDoc documentation I apparently missed: "Documentation comments not associated with a declaration are ignored." (from http://www.d-programming-language.org/ddoc.html) ...which in turn is not logical to me because the condition "/**" and "*/" are met. Anyway, thanks for the help; it guided me in the right direction. Thanks again

Am 16.12.2011, 19:45 Uhr, schrieb dune <do-not@email.com>: > I didn't realize that stuff like this will not work as expected: > > [code] > /*********************************** > * Brief summary of what > * myfunc does, forming the summary section. > * > * First paragraph of synopsis description. > * > * Second paragraph of > * synopsis description. > */ > > void myfunc() { } > > /*********************************** > * This is just some text that > * should be added to the > * documentation > */ > > // below is the next chunk of code > [/code] > > The second block of documentation will not show up. How is the doc generator supposed to know where that doc fragment is supposed to end up? If it's related to a declaration, put it there. If it's just a module-level comment, put it into the module doc comment.

Forums