Walter wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
> 
> 

This looks like a great proposal.  The Ares working group has actually been around this topic a few times, and the consensus there was fairly close to what you've composed.  :)

If I may offer my $0.02:

- Is this just a style guide, or are you planning to give DMD (or a separate tool) the smarts to generate documentation?

- What will happen to symbols that are parsed, but do not have accompanying documentation?  Will they be emitted in the doc generation output?

- Won't there be a problem with nesting using the /+...+/ syntax for capturing comments?  IMHO, it might be best to just ignore that comment type and just use them for commenting out the other more 'sensitive' comment types.

- I know that there are bound to be some sharp criticisms for this but I strongly feel that providing intermediate output to XML would be a wise choice for a doc generator.  It would allow one to apply a stylesheet via a browser or third-party tool, to generate documentation in a whole host of formats (Plain-text, HTML, Postscript, LaTEX, etc).  Such intermediate XML files can also be further processed into crosss-references, indexes and such by additional stylesheet transforms.

That way if anyone doesn't like the way the standard doc generator writes HTML, they can easily take a different tact.  Not even Javadoc or  Doxygen lets us do that.

-- 
- EricAnderton at yahoo

"pragma" <EricAnderton@youknowthedrill.yahoo> wrote in message news:dfcqik$gfj$1@digitaldaemon.com...
> - Is this just a style guide,

For the moment, yes.

> or are you planning to give DMD (or a
> separate tool) the smarts to generate documentation?

It would be part of DMD, that way it can take advantage of DMD's symbol table.

> - What will happen to symbols that are parsed, but do not have accompanying documentation?  Will they be emitted in the doc generation output?

They'll be there, too. Having an empty description for it will encourage writing one <g>.

> - Won't there be a problem with nesting using the /+...+/ syntax for capturing comments?  IMHO, it might be best to just ignore that comment type and just use them for commenting out the other more 'sensitive' comment types.

I don't see the problem?

> - I know that there are bound to be some sharp criticisms for this but I strongly feel that providing intermediate output to XML would be a wise choice for a doc generator.  It would allow one to apply a stylesheet via a browser or third-party tool, to generate documentation in a whole host of formats (Plain-text, HTML, Postscript, LaTEX, etc).  Such intermediate XML files can also be further processed into crosss-references, indexes and such by additional stylesheet transforms.
>
> That way if anyone doesn't like the way the standard doc generator
> writes HTML, they can easily take a different tact.  Not even Javadoc or
>   Doxygen lets us do that.

XML output is certainly possible. I tried to avoid in the specification what the output format would be.

In article <dfa6th$190j$1@digitaldaemon.com>, Walter says...
>"Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:df9keh$kvi$1@digitaldaemon.com...
<snip>
>> It ought to be specified that HTML character entities, at least &lt; &gt; &amp; will be rendered as their respective characters regardless of the output format.  That way, it would be possible to use these symbols in documentation and they will still work when generating documentation in non-HTML.
>
>Since the D source character set is unicode, any unicode characters can be embedded. Using character entities will simply be copied to the output.
<snip>

I don't see what that's to do with my point.  How does one embed a less than sign then?

Stewart.

Thank you for answering my questions Walter. :)

Walter wrote:
>>- Won't there be a problem with nesting using the /+...+/ syntax for
>>capturing comments?  IMHO, it might be best to just ignore that comment
>>type and just use them for commenting out the other more 'sensitive'
>>comment types.
> 
> 
> I don't see the problem?

/++
+  Some documentation here
+
/++
+ More documentation here
+
+/
/**
* Even more documentation here
*/
+/

The problem is that the case isn't clearly documented.  Rather than introduce rules that may not be what the developer would expect.

The easiest way to "solve" this is to throw out nested (/+...+/) comments completely as to avoid this similar cases completely.  It would also give the developer a way to tell the doc generator to ignore otherwise "capturable" comment blocks (so we don't have to kludge things with a version() statement instead).

-- 
- EricAnderton at yahoo

"Stewart Gordon" <Stewart_member@pathlink.com> wrote in message news:dfekd2$210h$1@digitaldaemon.com...
> In article <dfa6th$190j$1@digitaldaemon.com>, Walter says...
> >"Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:df9keh$kvi$1@digitaldaemon.com...
> <snip>
> >> It ought to be specified that HTML character entities, at least &lt; &gt; &amp; will be rendered as their respective characters regardless
of
> >> the output format.  That way, it would be possible to use these symbols in documentation and they will still work when generating documentation in non-HTML.
> >
> >Since the D source character set is unicode, any unicode characters can
be
> >embedded. Using character entities will simply be copied to the output.
> <snip>
>
> I don't see what that's to do with my point.  How does one embed a less
than
> sign then?

I am not understanding what the issue is? If you use < characters, they get placed into the output. If that output is html, it may get interpreted as a tag. Therefore, you should probably use &lt;, which will get echoed as &, l, t, ; to the output.

"pragma" <EricAnderton@youknowthedrill.yahoo> wrote in message news:dfesml$27on$1@digitaldaemon.com...
> /++
> +  Some documentation here
> +
> /++
> + More documentation here
> +
> +/
> /**
> * Even more documentation here
> */
> +/
>
> The problem is that the case isn't clearly documented.  Rather than introduce rules that may not be what the developer would expect.

Comments appearing inside of doc comments will be simply echo'd to the output. That will make it easy to do things like embed source text inside a doc comment, as you'd just wrap it in /++ ... +/.

You have some good points.

I where think maybe it could be at good idea to
change the /++...+/ to document code.
So, that code between /++ ... +/ is both compiled and add to
the documentation.

and /** .. */ is only added to the documentation as usual.

In this way we can easy add the code and unit test to the docs.

On Fri, 02 Sep 2005 23:58:41 +1000, Derek Parnell wrote:

> On Fri, 02 Sep 2005 13:37:56 +0100, Stewart Gordon wrote:
> 
> [snip]
>> Examples as unittests are also a form of self-documenting code, and an excellent way to test the documented examples to make sure they work.
> [snip]
>> Conversely, not all examples make good unittests.
> [snip]
> 
> Yes, it would be useful to nominate specific unittests to be examples. It would also be useful to document other examples that are not unittests. For instance, it would not be practical to execute unittests on a function that displays a dialog window each time, or a function that reformats your hard drive each time, etc ... But we still might want to show examples of its usage.

Actually you can document this type of unit test as documentation.

What you could do is to abstract the interface on the window system or driver, make a mock class with the same interface and then test your code on the mock object.

This type of test gives a lot of benefits. (search google for mock objects)

Here it is important to remember that unit test should test the your code
is correct not that the window system or driver are correct. Such,
that you know that if the unit test fails it is your code or your unit
test which is in error.

If you need to test the window system you should run the unit test for the window system or you functional tests.

Knud

Walter wrote:
> "Stewart Gordon" <Stewart_member@pathlink.com> wrote in message news:dfekd2$210h$1@digitaldaemon.com...
>> In article <dfa6th$190j$1@digitaldaemon.com>, Walter says...
>>> "Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:df9keh$kvi$1@digitaldaemon.com...
>> <snip>
>>>> It ought to be specified that HTML character entities, at least
>>>> &lt; &gt; &amp; will be rendered as their respective characters regardless of the output format.  That way, it would
>>>> be possible to use these symbols in documentation and they will still work when generating documentation in non-HTML.
>>> 
>>> Since the D source character set is unicode, any unicode characters can be embedded. Using character entities will simply be copied to the output.
>> <snip>
>> 
>> I don't see what that's to do with my point.  How does one embed a less than sign then?
> 
> I am not understanding what the issue is? If you use < characters, they get placed into the output. If that output is html, it may get interpreted as a tag. Therefore, you should probably use &lt;, which will get echoed as &, l, t, ; to the output.

If the output is not HTML, then the reader of the output will just see &, l, t, ; in the rendered document.  Under your current proposal, if someone wants to generate non-HTML documentation from source files written for HTML output, he/she/it will have to go through the source files replacing all &lt; with <.  And then when it's time to update the HTML documentation again, go through changing it back while having a care not to alter those that are part of the code itself.

It should be as possible as possible to write code documentation that works regardless of output format.  Of course converting all HTML tags into the target format isn't going to be easy, but translating &lt; into < if the output format isn't HTML certainly is.

Stewart.

-- 
-----BEGIN GEEK CODE BLOCK-----
Version: 3.1
GCS/M d- s:- C++@ 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.

Walter wrote:
> I've put up a strawman proposal for embedding documentation in comments at
> www.digitalmars.com/d/doc.html
> 
> 

This is to point out an alternative approach to documentation and source code. In the language machine (which is written in D and includes a d2d translator as one of its examples) I found it very useful to adopt a subset of the mediawiki (wikipedia) notation as the lexical form of input to the lmn metalanguage rule compiler.

In this approach, preformatted text (inset by at least one space) is treated as actual source, and everything else as comment, where the comment can include mediawiki markup.

This means that you can produce web pages directly from the source by applying the mediawiki ruleset, and it also means that you can put source directly onto a wiki and have it come out lokking fairly pretty - except that the mediawiki software doesn't treat the preformatted stuff as being also wrapped as <nowiki> </nowiki>. This seems to me pretty useful as enabling direct exchange of annotated source code fragments in a wiki.

I find that this approach is very natural and easy to use - you can see the results in (for example) the web page that is generated directly from the source text of the lmn metalanguage compiler front end:

http://languagemachine.sourceforge.net/lmn2xfe.html

Just a thought, in case it seems useful.

Peri

-- 
http://languagemachine.sourceforge.net - The language machine