DDoc module description?

Discussion:

Jeremy DeHaan via Digitalmars-d-learn

2014-10-19 01:11:38 UTC

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.

Gary Willoughby via Digitalmars-d-learn

2014-10-19 10:56:27 UTC

Permalink

Post by Jeremy DeHaan via Digitalmars-d-learn
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>

Jeremy DeHaan via Digitalmars-d-learn

2014-10-19 16:44:24 UTC

Permalink

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?

Gary Willoughby via Digitalmars-d-learn

2014-10-19 16:59:09 UTC

Permalink

Post by Jeremy DeHaan via Digitalmars-d-learn
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
<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.

Jeremy DeHaan via Digitalmars-d-learn

2014-10-19 17:26:04 UTC

Permalink

Post by Gary Willoughby via Digitalmars-d-learn

Post by Jeremy DeHaan via Digitalmars-d-learn
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
<html>

</html>
A module that contains blahblahblah.

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

Jeremy DeHaan via Digitalmars-d-learn

2014-10-19 17:43:50 UTC

Permalink

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.

Gary Willoughby via Digitalmars-d-learn

2014-10-19 18:19:25 UTC

Permalink

Post by Jeremy DeHaan via Digitalmars-d-learn
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

Jeremy DeHaan via Digitalmars-d-learn

2014-10-20 01:58:26 UTC

Permalink

Post by Gary Willoughby via Digitalmars-d-learn

Post by Jeremy DeHaan via Digitalmars-d-learn
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
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.

Gary Willoughby via Digitalmars-d-learn

2014-10-20 07:41:15 UTC

Permalink

Post by Jeremy DeHaan via Digitalmars-d-learn
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.