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
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
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 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 reply 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
parent reply 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
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