www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - DDoc module description?

reply "Jeremy DeHaan" <dehaan.jeremiah gmail.com> writes:
Although perhaps unnecessary, I added DDoc documentation to my 
module for a short description of the body. This showed up in the 
place I wanted it to be in when I built the html documentation, 
so I was pretty happy. (below the module name and before any 
module members)

I then went to override the DDOC macro to set it up with the 
correct formatting with the rest of the site I'll be putting the 
documentation on. The single line documentation I had written for 
the module apparently does not reside in BODY, and with the new 
formatting, it just casts it to the bottom of the page. It now 
resides below the footer.

Is there anything I can do to correct this? If not then I'll just 
say "screw it" and not bother, but I thought it looked pretty 
nice. Especially for modules that have more than one class in 
them.
Oct 18 2014
parent reply "Gary Willoughby" <dev nomad.so> writes:
On Sunday, 19 October 2014 at 01:11:39 UTC, Jeremy DeHaan wrote:

 Although perhaps unnecessary, I added DDoc documentation to my 
 module for a short description of the body. This showed up in 
 the place I wanted it to be in when I built the html 
 documentation, so I was pretty happy. (below the module name 
 and before any module members)

 I then went to override the DDOC macro to set it up with the 
 correct formatting with the rest of the site I'll be putting 
 the documentation on. The single line documentation I had 
 written for the module apparently does not reside in BODY, and 
 with the new formatting, it just casts it to the bottom of the 
 page. It now resides below the footer.

 Is there anything I can do to correct this? If not then I'll 
 just say "screw it" and not bother, but I thought it looked 
 pretty nice. Especially for modules that have more than one 
 class in them.


It's hard to tell what's gone wrong but i'm guessing something 
has been missed in your macro. For reference this is my ddoc file 
that i use for generating html and it works great:

DDOC = <!DOCTYPE HTML>
<html>
	<head>
		<meta http-equiv="content-type" content="text/html; 
charset=utf-8" />
		<link type="text/css" 
href="http://www.nomad.so/ddoc/css/theme.css" rel="stylesheet" 
media="all" />
		<script type="text/javascript" 
src="http://www.nomad.so/ddoc/javascript/jquery-2.0.3.min.js"></script>
		<script type="text/javascript" 
src="http://www.nomad.so/ddoc/javascript/jquery.scrollTo.min.js"></script>
		<script type="text/javascript" 
src="http://www.nomad.so/ddoc/javascript/index.js"></script>
		<title>$(TITLE)</title>
	</head>
	<body>
		<h1>$(TITLE)</h1>
		$(BODY)
	</body>
</html>
H2 = <h2>$0</h2>
H3 = <h3>$0</h3>
STRONG = <strong>$0</strong>
EM = <em>$0</em>
PRE = <pre>$0</pre>

PARAM_TABLE = <table class="parameter-list">$0</table>
PARAM_ROW = $(TR $(TD $1)$(TD $2))

DDOC_DECL = $(H2 $0)
DDOC_DECL_DD = <div class="declaration-description">$0</div>

DDOC_CLASS_MEMBERS = <div class="class-members">$0</div>
DDOC_SUMMARY = $(P $0)
DDOC_DESCRIPTION = $(P $0)

DDOC_MEMBERS = <div class="members">$0</div>
DDOC_ENUM_MEMBERS = <div class="enum-members">$0</div>
DDOC_MODULE_MEMBERS = <div class="module-members">$0</div>
DDOC_STRUCT_MEMBERS = <div class="struct-members">$0</div>
DDOC_TEMPLATE_MEMBERS = <div class="template-members">$0</div>

DDOC_SECTIONS = <div class="sections">$0</div>
DDOC_SECTION = $(P $0)
DDOC_SECTION_H = $(H3 $0)

DDOC_PARAMS = $(H3 Parameters)$(PARAM_TABLE $0)
DDOC_PARAM_ROW = $(TR $0)
DDOC_PARAM_ID = $(TD $0)
DDOC_PARAM_DESC = $(TD $0)

DDOC_AUTHORS = $(H3 Authors)$(P $0)
DDOC_BUGS = $(H3 Bugs)$(P $0)
DDOC_COPYRIGHT = $(H3 Copyright)$(P $0)
DDOC_DATE = $(H3 Date)$(P $0)
DDOC_DEPRECATED = $(H3 Deprecation Information)$(P $0)
DDOC_EXAMPLES = $(H3 Examples)$(P $0)
DDOC_HISTORY = $(H3 History)$(P $0)
DDOC_LICENSE = $(H3 License)$(P $0)
DDOC_RETURNS = $(H3 Return Value)$(P $0)
DDOC_SEE_ALSO = $(H3 See Also)$(P $0)
DDOC_STANDARDS = $(H3 Standards)$(P $0)
DDOC_THROWS = $(H3 Exceptions Thrown)$(P $0)
DDOC_VERSION = $(H3 Version Information)$(P $0)

DDOC_PSYMBOL = <span class="symbol">$0</span>
DDOC_PSUPER_SYMBOL = <span class="super-symbol">$0</span>
DDOC_KEYWORD = $(STRONG $0)
DDOC_PARAM = $0

D_CODE = $(PRE $0)
D_COMMENT = <span class="comment">$0</span>
D_STRING = <span class="string">$0</span>
D_KEYWORD = <span class="keyword">$0</span>
D_PSYMBOL = <span class="symbol">$0</span>
D_PARAM = <span class="parameter">$0</span>
Oct 19 2014
parent reply "Jeremy DeHaan" <dehaan.jeremiah gmail.com> writes:
Thanks for the reply. I just went through it and I didn't see 
anything that was missed. I'll post this here so that maybe 
someone can see something I am missing.

DDOC = <html>
<head>
<META http-equiv="content-type" content="text/html; 
charset=utf-8">
<link rel="stylesheet" type="text/css" media="screen" 
href="stylesheets/stylesheet.css">
<title>$(TITLE)</title>
</head>
<body>

<!-- HEADER  -->
<div id="header_wrap" class="outer">
<header class="inner">
	<a id="forkme_banner" href="https://github.com/Jebbs/DSFML">View 
on GitHub</a>
	<h1 id="project_title">DSFML</h1>
	<section id="downloads">
		<a class="zip_download_link" 
href="https://github.com/Jebbs/DSFML/zipball/master">Download 
this project as a .zip file</a>
		<a class="tar_download_link" 
href="https://github.com/Jebbs/DSFML/tarball/master">Download 
this project as a tar.gz file</a>
	</section>
</header>
</div>

<!-- MAIN BODY  -->
<div id="main_content_wrap" class="outer">
	<section id="main_content" class="inner">
		<h1>$(TITLE)</h1>
		$(BODY)
	</section>
</div>

<!-- FOOTER  -->
<div id="footer_wrap" class="outer">
<footer class="inner">
</footer>
</div>
</body>
</html>


The problem seems to be when I do something like this.

*blah.d*

///A module that contains blahblahblah.
module something.blah;

//Stuff goes here

What will end up happening is the generated html file turns out 
like this:

<html>
     <!-- All the generated stuff here -->
</html>
A module that contains blahblahblah.


As you can see, the module description is put outside the html 
tag. If I don't redefine the DDOC macro, it will place the module 
description inside the body tag just after <h1>$(TITLE)</h1>. Is 
this a DDoc bug?
Oct 19 2014
parent reply "Gary Willoughby" <dev nomad.so> writes:
On Sunday, 19 October 2014 at 16:44:25 UTC, Jeremy DeHaan wrote:

 The problem seems to be when I do something like this.

 *blah.d*

 ///A module that contains blahblahblah.
 module something.blah;

 //Stuff goes here

 What will end up happening is the generated html file turns out 
 like this:

 <html>
     <!-- All the generated stuff here -->
 </html>
 A module that contains blahblahblah.


Try it using a normal comment style like this:

     /**
      * A module that contains blahblahblah.
      */
     module something.blah;

See if that compiles differently, it may be a bug with triple 
slash comments.
Oct 19 2014
parent reply "Jeremy DeHaan" <dehaan.jeremiah gmail.com> writes:
On Sunday, 19 October 2014 at 16:59:10 UTC, Gary Willoughby wrote:

 On Sunday, 19 October 2014 at 16:44:25 UTC, Jeremy DeHaan wrote:

 The problem seems to be when I do something like this.

 *blah.d*

 ///A module that contains blahblahblah.
 module something.blah;

 //Stuff goes here

 What will end up happening is the generated html file turns 
 out like this:

 <html>
    <!-- All the generated stuff here -->
 </html>
 A module that contains blahblahblah.


 Try it using a normal comment style like this:

     /**
      * A module that contains blahblahblah.
      */
     module something.blah;

 See if that compiles differently, it may be a bug with triple 
 slash comments.


No change. It still places the comment outside the html tag.
Oct 19 2014
parent reply "Jeremy DeHaan" <dehaan.jeremiah gmail.com> writes:
That's ok though. I can live with out it. I'll look through the 
bugzilla site and see if I can find a bug report for this or open 
up a new one.

On a side note, is there any way that I can redefine the DDOC 
macro (or any other macro) once and have it be used for every 
file? That was the only thing I couldn't seem to find in the 
documentation for it.
Oct 19 2014
parent reply "Gary Willoughby" <dev nomad.so> writes:
On Sunday, 19 October 2014 at 17:43:51 UTC, Jeremy DeHaan wrote:

 That's ok though. I can live with out it. I'll look through the 
 bugzilla site and see if I can find a bug report for this or 
 open up a new one.

 On a side note, is there any way that I can redefine the DDOC 
 macro (or any other macro) once and have it be used for every 
 file? That was the only thing I couldn't seem to find in the 
 documentation for it.


Just add the following line to your dmd.conf file (on GNU/Linux) 
or sc.ini file (on Windows):

     DDOCFILE=file

http://dlang.org/dmd-windows.html#sc-ini
http://dlang.org/dmd-linux.html#dmd-conf
Oct 19 2014
parent reply "Jeremy DeHaan" <dehaan.jeremiah gmail.com> writes:
On Sunday, 19 October 2014 at 18:19:26 UTC, Gary Willoughby wrote:

 On Sunday, 19 October 2014 at 17:43:51 UTC, Jeremy DeHaan wrote:

 That's ok though. I can live with out it. I'll look through 
 the bugzilla site and see if I can find a bug report for this 
 or open up a new one.

 On a side note, is there any way that I can redefine the DDOC 
 macro (or any other macro) once and have it be used for every 
 file? That was the only thing I couldn't seem to find in the 
 documentation for it.


 Just add the following line to your dmd.conf file (on 
 GNU/Linux) or sc.ini file (on Windows):

     DDOCFILE=file

 http://dlang.org/dmd-windows.html#sc-ini
 http://dlang.org/dmd-linux.html#dmd-conf


Is there no way to specify one at compile time?

Also, if I were to set the DDoc file like you suggest, does it 
look for one locally to dmd.conf/sc.ini or to the source code?



Additionally, I found out what was going on. When I redefined 
DDOC, I did so right before the module description so it ended up 
combining the two documentation blocks together putting the 
description after the html block. I just swapped them so that the 
module description appeared before I redefined the DDOC macro and 
it worked as expected again.
Oct 19 2014
parent "Gary Willoughby" <dev nomad.so> writes:
On Monday, 20 October 2014 at 01:58:27 UTC, Jeremy DeHaan wrote:

 Is there no way to specify one at compile time?
 
 Also, if I were to set the DDoc file like you suggest, does it 
 look for one locally to dmd.conf/sc.ini or to the source code?


See here for full information: http://dlang.org/ddoc.html
The compiler checks in various places for a valid ddoc file.
Oct 20 2014