www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - -D option = Embedded documentation

reply dune <do-not email.com> writes:
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?
Dec 16 2011
parent reply Trass3r <un known.com> writes:
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.
Dec 16 2011
next sibling parent reply dune <do-not email.com> writes:
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
Dec 16 2011
parent reply Timon Gehr <timon.gehr gmx.ch> writes:
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>
Dec 16 2011
parent dune <do-not email.com> writes:
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
Dec 16 2011
prev sibling next sibling parent Trass3r <un known.com> writes:
 What I posted was an example, in reality there is tons of code inside  
 the d file.

Show the file, or part of it.
Dec 16 2011
prev sibling next sibling parent Trass3r <un known.com> writes:
          <hr><small>Page generated by <a  
 href="http://www.digitalmars.com/d/2.0/ddoc.html">Ddoc</a>. </small>
          </body></html>

Ah looks like that must be updated to dlang.org too
Dec 16 2011
prev sibling parent Trass3r <un known.com> writes:
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.
Dec 16 2011