Walter wrote:
> Here's an example of how I use it, this is std_random.txt, the eventual html
> is at www.digitalmars.com/d/phobos/std_random.html
> 
> The header, footer, and sidebar are all boilerplate from macros.inc.
<snip>

Looks like the preprocessor at the moment is little more than a workaround for HTML not having client-side includes.

For that matter, how do blocks of BNF or D code look in your input files?

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- a->--- UB@ P+ L E@ W++@ N+++ o K- w++@ O? M V? PS- PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on the 'group where everyone may benefit.

> There's also </p>, which marks the end of a paragraph, but that's optional....

No, it isn't. It was optional. Nowadays everybody should write correct XHTML.

Ciao
uwe

Uwe Salomon wrote:
> 
>> There's also </p>, which marks the end of a paragraph, but that's  optional....
> 
> No, it isn't. It was optional. Nowadays everybody should write correct  XHTML.

In order to start writing correct XHTML, one must start writing XHTML. Which means, first things first, that the document must identify itself as XHTML.

Even if you ignore DOCTYPE declarations, a page cannot be both HTML and XHTML at the same time if it uses <img> or other tags that don't have closing versions.

But still, there are people who feel it's good practice to include all the closing tags regardless.  I do it myself.

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- a->--- UB@ P+ L E@ W++@ N+++ o K- w++@ O? M V? PS- PE- Y? PGP- t- 5? X? R b DI? D G e++>++++ h-- r-- !y
------END GEEK CODE BLOCK------

My e-mail is valid but not my primary mailbox.  Please keep replies on the 'group where everyone may benefit.

"Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:dehfu9$1ujl$1@digitaldaemon.com...
> Walter wrote:
> > Here's an example of how I use it, this is std_random.txt, the eventual
html
> > is at www.digitalmars.com/d/phobos/std_random.html
> >
> > The header, footer, and sidebar are all boilerplate from macros.inc.
> <snip>
>
> Looks like the preprocessor at the moment is little more than a workaround for HTML not having client-side includes.

That's right. It's a trivial program, but very useful.

> For that matter, how do blocks of BNF or D code look in your input files?

$(CODE_S)
    void main()
    {
        writefln("hello world\n");
    }
$(CODE_E)

That way, I can experiment with various schemes of marking code without having to edit hundreds of files. The macros are currently defined as:

.set CCODE_S=<p><table border=0 cellspacing=2 cellpadding=8
bgcolor="#cccccc">
        <tr bgcolor="#EEDDEE"><td width=600> \
        <pre><font color="#000066" face="mono">
.set CCODE_E=</font></td></pre></tr></table><p>


.set CODE_S=<p><table border=0 cellspacing=2 cellpadding=8
bgcolor="#cccccc"> \
        <tr bgcolor="#e7e7e7"><td width=600> \
        <pre><font color="#000066" face="mono">
.set CODE_E=</font></td></pre></tr></table><p>

.set CODE_S=<p><table border=0 cellspacing=2 cellpadding=8
bgcolor="#cccccc"> \
        <tr bgcolor="#e7e7e7"><td width=600> \
        <pre><font color="#000066" face="mono">
.set CODE_E=</font></td></pre></tr></table><p>


.set GRAMMAR_S=<p><table border=0 cellspacing=2 cellpadding=8
bgcolor="#cccccc"> \
        <tr bgcolor="#FEFEFE"><td width=600> \
        <pre><font color="#060666" face="mono">
.set GRAMMAR_E=</font></td></pre></tr></table><p>

> While it's a good idea, I find it just aesthetically ugly in the program source code.

Well, then put it in a "comment behind" file. (Or change it to your liking. While it's hard form me to accept "aesthetically ugly" in contradiction with usabilty, I can also point that even phobos has different comments, with "//" on variables and some general comments with "/* */".)

I can't emphasize enough how excellent a something-like-XML-comment would
be. Why?
Based on your sample on random, I've made it in C#. Let me show you the
usability of that in pictures (It is said that one picture is hundred times
better than a word, in my case at least hundred and eighty ;) ).

The simple sample base in the code editor (Visual Studio): http://elfqt.simeis.hu/szallit/DComm/Dcomm1.jpg

The code used: http://elfqt.simeis.hu/szallit/DComm/CommentTemp.cs

Finding it ugly? Hide it: http://elfqt.simeis.hu/szallit/DComm/Dcomm1b.jpg

When you type (well, select with intellisense) a method (which, of course
should be any class, funct, enum etc.), you get the "help" right there
(Don't have to browse, search another doc somewhere else.)
http://elfqt.simeis.hu/szallit/DComm/Dcomm2.jpg

Using my own code, or Phobos library, or everybody else's lib/code, right there at the use I can get at least a min-help, not to mention that see the signatures of calls and returns and all. http://elfqt.simeis.hu/szallit/DComm/Dcomm3.jpg

Every variable can have it's own comment, and it will also show at the place
of use:
http://elfqt.simeis.hu/szallit/DComm/Dcomm4.jpg

If you have any number of overloads on a method, sometimes it's hard to find and match with the right one, well not with xml comment and a good editor. You can go up and down in the list of overloaded calls (and you can easily check on the parameters of each): http://elfqt.simeis.hu/szallit/DComm/Dcomm5.jpg

You can use (semi)standard doc generating tools:
Just from the little one code file NDoc generates this help:
http://elfqt.simeis.hu/szallit/DComm/Dcomm6.jpg
http://elfqt.simeis.hu/szallit/DComm/Dcomm6b.jpg

(I've uploaded the generated chm
too:http://elfqt.simeis.hu/szallit/DComm/Documentation.chm)

And well, what is the output, when the compiler gathers the XMl comment?
Another xml file:
http://elfqt.simeis.hu/szallit/DComm/CommentTemp.xml
Why is that interesting? Because if you use something in compiled form, but
it has a corresponding definition, tools can use it really well: "Object
browser" can show the same info like the above:
http://elfqt.simeis.hu/szallit/DComm/Dcomm7.jpg

Also, I am not an expert of that, just a "user" - there is more in the
commenting system syntax and usage (all in all, you _can_ write comments
then generate help with the content and detail like msdn library).
OK, D is "just a compiler". But Phobos is a library. A compiler and a
library is almost a platform.
For a new language (platform, library), well let me say, in the spread of a
new language, one important aspect is the learning curve, which mostly
emerge with it's standard library.
If you want programmers to learn to use libraries as fast as they can, give
them a method like this: let them access the info on needed classes,
methods, parameters rigth where they use it.

If you not formalize comments, then you cannot ensure that the code and the
docs will be the same. (Well, considering that C# compiler gives warning (of
yourse, everyone should use 'treat warning ass error') if comment is missing
or differs.)
The goal should be no less than to include the full doc generation in the
build process (yes, that's how I do it now).

In my personal opinion, when I have to browse the phobos code and the published phobos doc just to find function names and parameters (many times with find in files - until there is not a working editor capable of 'go to definition' function, which in terms of usability is also in connection with formalized commenting) is frustrating on contrast of the ways I tried to describe in this message.

I hope you (Walter, and also all the contributors, whom I really respect for what's already accomplished), not find my opinion (and _not_ demand) pushy. There is so much things concerning D that I can't contribute in lack of understanding and experience in compiler technology and low level programming and library design, but if there is something in what I have solid view then the above was one of it.

ElfQT (you can reach me at elfqt p1 simeis p2 hu - where p1 is at, p2 is
dot)

I agree completely with you on the usefulness of automatic documentation generation from the source (after all, it fits right in with the idea of embedded contracts and unit tests). I just find the C# approach used to be overcomplicated and ugly in its source form. For example, instead of:

    /// <summary> starting seed </summary>
    private static uint seed;

Wouldn't it be more natural as:

    private static uint seed;    /// starting seed

? And:

/// <summary>
		/// The random number generator is seeded at program startup with a random
value.
		/// This ensures that each program generates a different sequence of
random  numbers.
		/// To generate a repeatable sequence, use <see cref="rand_seed(uint,
uint)"/> to start the sequence.
		/// The parameters start it, and each successive value increments index.
This means that the nth random number of the sequence can be directly
generated by passing index + n to <see cref="rand_seed(uint, uint)"/>.
		/// </summary>
/// <param name="s">the random number seed</param>
		/// <param name="i">each successive value increments index</param>
		/// <returns>void</returns>
		public static void rand_seed(uint s, uint i)
		{
			seed = s;
			index = i;
		}

The compiler knows that the return value is void. Why should the programmer have to type it in twice? It's going to be something you have to force programmers to do, rather than it coming naturally. Why should the programmer have to identify the parameters twice? This could work:

/// The random number generator is seeded at program startup with a random
value.
/// This ensures that each program generates a different sequence of random
numbers.
/// To generate a repeatable sequence, use <see cref="rand_seed(uint,
uint)"/> to start the sequence.
/// The parameters start it, and each successive value increments index.
This means that the nth random
/// number of the sequence can be directly generated by passing index + n to
rand_seed(uint, uint)
public static void rand_seed(
        uint s,    /// the random number seed
        uint i)    /// each successive value increments index
{
seed = s;
index = i;
}

The idea is to make the compiler do the work rather than the programmer. So while I agree completely with you on the advantages of doing this, I only disagree with the form that C# and Javadoc take, as they are needlessly and excessively klunky.

It wouldn't be too hard to adjust dmd to extract and output this info.

Walter wrote:
> public static void rand_seed(
>         uint s,    /// the random number seed
>         uint i)    /// each successive value increments index
> {
> seed = s;
> index = i;
> }

Just thought I'd mention this is pretty close to my current coding style anyhow, so I'm all set and in support of it.  *g*  Except mine tend to look more like:

# public static void rand_seed (
#   in uint s , // the random number seed
#   in uint i   // each successive value increments index
# )
# in {
#   // some rules for the seed...
# }
# body {
#   seed  = s ;
#   index = i ;
# }

So if this standard convention were adopted... all I'd have to do is triplize a few slashes?  That'd be nifty.

-- Chris Sauls

In article <dekveh$2a28$1@digitaldaemon.com>, Walter says...
>
>I agree completely with you on the usefulness of automatic documentation generation from the source (after all, it fits right in with the idea of embedded contracts and unit tests). I just find the C# approach used to be overcomplicated and ugly in its source form. For example, instead of:
>
>    /// <summary> starting seed </summary>
>    private static uint seed;
>
>Wouldn't it be more natural as:
>
>    private static uint seed;    /// starting seed
>
>? And:
>
>/// <summary>
>		/// The random number generator is seeded at program startup with a random
>value.
>		/// This ensures that each program generates a different sequence of
>random  numbers.
>		/// To generate a repeatable sequence, use <see cref="rand_seed(uint,
>uint)"/> to start the sequence.
>		/// The parameters start it, and each successive value increments index.
>This means that the nth random number of the sequence can be directly
>generated by passing index + n to <see cref="rand_seed(uint, uint)"/>.
>		/// </summary>
>/// <param name="s">the random number seed</param>
>		/// <param name="i">each successive value increments index</param>
>		/// <returns>void</returns>
>		public static void rand_seed(uint s, uint i)
>		{
>			seed = s;
>			index = i;
>		}
>
>The compiler knows that the return value is void. Why should the programmer have to type it in twice? It's going to be something you have to force programmers to do, rather than it coming naturally. Why should the programmer have to identify the parameters twice? This could work:
>
>/// The random number generator is seeded at program startup with a random
>value.
>/// This ensures that each program generates a different sequence of random
>numbers.
>/// To generate a repeatable sequence, use <see cref="rand_seed(uint,
>uint)"/> to start the sequence.
>/// The parameters start it, and each successive value increments index.
>This means that the nth random
>/// number of the sequence can be directly generated by passing index + n to
>rand_seed(uint, uint)
>public static void rand_seed(
>        uint s,    /// the random number seed
>        uint i)    /// each successive value increments index
>{
>seed = s;
>index = i;
>}
>
>The idea is to make the compiler do the work rather than the programmer. So while I agree completely with you on the advantages of doing this, I only disagree with the form that C# and Javadoc take, as they are needlessly and excessively klunky.

You have my vote for your suggested syntax. It looks good! Nice and simple.

--AJG.

On Thu, 25 Aug 2005 10:32:41 -0700, Walter wrote:

> I agree completely with you on the usefulness of automatic documentation generation from the source (after all, it fits right in with the idea of embedded contracts and unit tests). I just find the C# approach used to be overcomplicated and ugly in its source form. For example, instead of:
> 
>     /// <summary> starting seed </summary>
>     private static uint seed;
> 
> Wouldn't it be more natural as:
> 
>     private static uint seed;    /// starting seed

I agree in principle with you Walter. There is slight complication when you need multiple text lines to describe the item though. Maybe ...

  private static uint seed;    /*/ Starting seed. This is automatically
                                   set to a different random value each
                                   time the application is run.
                               /*/

> ? And:
> /// The random number generator is seeded at program startup with a random
> value.
> /// This ensures that each program generates a different sequence of random
> numbers.
> /// To generate a repeatable sequence, use <see cref="rand_seed(uint,
> uint)"/> to start the sequence.
> /// The parameters start it, and each successive value increments index.
> This means that the nth random
> /// number of the sequence can be directly generated by passing index + n to
> rand_seed(uint, uint)
> public static void rand_seed(
>         uint s,    /// the random number seed
>         uint i)    /// each successive value increments index
> {
> seed = s;
> index = i;
> }

Another complication is when you need to describe the result value.

 public static uint /// The current seed value.
  rand_seed(
         uint s,    /// the random number seed
         uint i)    /// each successive value increments index
 {
 uint o = seed;
 seed = s;
 index = i;
 return o;
 }

This is starting to look hard to read. ;-)

Yet another complication. I try hard to always include examples of usage in my documentation. As there is no built-in D syntax to describe examples (unittest is the closest) how could we put that into extractable form. Maybe we don't need to make that stand out from the rest of the docs, but often its useful to display example code in a different (monospace) font.

///Sample{
///    uint OldValue;
///    OldValue = rand_seed( NewValue, theIndex);
///}


> The idea is to make the compiler do the work rather than the programmer. So while I agree completely with you on the advantages of doing this, I only disagree with the form that C# and Javadoc take, as they are needlessly and excessively klunky.

Very true.

> It wouldn't be too hard to adjust dmd to extract and output this info.

Well, off you go then ... by the end of next week would be just fine ;-)

-- 
Derek Parnell
Melbourne, Australia
26/08/2005 6:30:44 AM

I'm glad you agree with the use of it.
I don't force or promote c# style - I've used is as an example - any similar
will suffice.
(Although I believe the c# style, or at least the different tags and all, is
not a bad one - they already walked the path that we are on now, I will
describe it later in this post.)

>> /// <returns>void</returns>
> The compiler knows that the return value is void. Why should the
> programmer
> have to type it in twice?
Well ;) I was lazy. <returns> should describe the meaning of the return value. its a description not a type indication. There's no meaning in documenting void (well, at least in most cases).

>    private static uint seed;    /// starting seed
Well that's good also. I guess they are using xml tags to indicate the start _and_ the end unmistakenly. (We need a standard on how to indicate multiple lines too.)

> /// ... long desc snipped by ElfQT...
> rand_seed(uint, uint)
> public static void rand_seed(
>        uint s,    /// the random number seed
>        uint i)    /// each successive value increments index

All right that looks good, even better from your expressed point of view,
but consider that
 - this way you always have to break parameters to separate lines
 - maybe not everyone wants to write all the comment, it has to work with or
without
 - you can't "collapse" (hide all the comments at once) - well at least you
can collapse the "long", summarizing description.

Aside of that the format is good - as any standard and well thought format is good.

So, at the given msdn lib. link
(http://msdn.microsoft.com/library/default.asp?url=/library/en-us/csref/html/vcoriXMLDocumentation.asp)
I recommend "Recommeded tags" - not to use them as copy it mindlessly, but
as what possibilities are in such commenting. My short version:
All tags are xml, so there is a open and a close (<c> </c>), I will only
write the open as a "comment type".

<c> and <code> indicating code (inside the comment block, not the actual
code) <code> indicates multiple lines of code.
<example> before the code, you can write about the following code
This two (example and code) in a generated output can indicate formatted
section of "Example" - description, and then example code.
<include file='filename' path='tagpath[@name="id"]' /> - lets you refer to
comments in another file.

With <list> and <listheader> - well, guess you can make a list. <para> - paragraph

Ok, you got me with this two - maybe formatting the comment (more precisely to control the output of the comment) is a bit strange. The goal with c# probably was to be able to generate msdn lib content, or very similar. Maybe D donesn't need that.

<remarks> - well summary is planned to be short - that will appear on the fly with code editors. <remarks> is the long description - also there is a "Remarks" section in msdn doc style...

<see> - lets you create links to other members
<seealso> - the listing of "See also" sections links

Not that interesting or important:
<exception cref="member">
<param> - now we all know it, and will probably reject that format.
<paramref> - but with this, you can refer to a given param
<permission> - thats .net specific
<value> - c# property specific

Now I try to gather what is needed.
Comment on structs, interfaces, classes, methods and functions, enums,
typedefs, properties, templates.
I recommend to use a summarizing form and an optional longer description for
classes, methods and functions, maybe teampaltes also.
I like the given simply form, but how to comment the return value?

/// here comes a summary. it can
/// multi line
///d long long long long
///d long long description
///r the meaning if the return value (if its not void)
public static void rand_seed(
       uint s,    /// the random number seed
       uint i)    /// each successive value increments index

Somehow we need to indicate (differentiate in the comment text):
"description" (the long one, not the summary), comment on return value, link
to another code element (class, enum, method etc.).
Is there any more useful type of comment element? Does it need something to
control documentation output like standard documentation sections (like
<code>, <seealso>, <example>?

Do we need triple slashes? Are these comments different from two slash
standard comments? (I guess its easier to extract the triple ones, without
exactly parsing and analyzing of the comment is at a place in the
source, which place indicates if that comment is needed in the doc, or just
a "simple" comment.)

Also, any class level variable should use the commenting format - and clever tools should support that also (when moving the cursor to a use of that variable, or typing it, the info should appear.)

Ok that was just my past midnight rambling started by the positive reaction - I will be glad even with a simple form without making short summary and longer description and without any of the rest (but still there is a need to comment on return value)).

Also, now I found Derek's post pointing out multiline comment, and return value comment, and even example code. I dont like the linebreak with return value comment.

Regards,
 ElfQT