DDoc module description?

Oct 19, 2014

Jeremy DeHaan

Oct 19, 2014

Gary Willoughby

Oct 19, 2014

Oct 19, 2014

Oct 19, 2014

Oct 19, 2014

Oct 19, 2014

Oct 20, 2014

Oct 20, 2014

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.

October 19, 2014

Re: DDoc module description?

Posted by Gary Willoughby
in reply to Jeremy DeHaan

Permalink

Gary Willoughby

Posted in reply to Jeremy DeHaan

Permalink

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>

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>  <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>  <div id="main_content_wrap" class="outer"> <section id="main_content" class="inner"> <h1>$(TITLE)</h1> $(BODY) </section> </div>  <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>  </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?

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> >  > </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.

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> >>  >> </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.

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.

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

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.

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.

Forums