"Knud Sørensen" <12tkvvb02@sneakemail.com> wrote in message news:pan.2005.08.31.09.46.08.415427@sneakemail.com...
> What I am missing is a way to add the unit test to the documentation as examples.
>
> Most auto-generated documents doesn't have enough examples.

True, but unit tests generally make for poor examples.

On Wed, 31 Aug 2005 11:37:50 -0700, Walter wrote:

> 
> "Freejack" <freejack@nowhere.net> wrote in message news:pan.2005.08.28.17.31.04.603691@nowhere.net...
>> On Sat, 27 Aug 2005 01:47:18 -0700, Walter wrote:
>>
>> > I've put up a strawman proposal for embedding documentation in comments
> at
>> > www.digitalmars.com/d/doc.html
>>
>> Have you considered going the whole route and adding formalized annotations for Splint and ASIS like tools? Look at the Spark system from Praxis High Integrity Systems (www.praxis-his.com/sparkada/)to see what I mean.
> 
> It seems way beyond what we're doing here <g>.

Probably. I wasn't suggesting creating an entire subsystem for that specific purpose. I was thinking more along the lines of ASIS-lite. Just a few generalized hooks into the system would be all that D needs, rather than the whole hog that an Asis like specification would require. Later on, others could come along and build on that foundation.

Just a thought.

Freejack

Walter wrote:
>>From that you can't tell if class D is documented for real, or just been
>>forgotten. That's a problem because compiler should falsely use the
<snip>
> The reason I put it in like that is sometimes one documents as a group a set
> of related functions, such as:
> 
>     float sin(float)
>     double sin(double)
>     real sin(real)
> 
> and it's just feels stupid to have to separately document them with
> cut/paste. I understand the problem you're describing, though, and I don't
> see a solution to it other than "don't do that" :-(

I really don't like comments falling through. Much better to give some way to explicitly inherit a comment from something else.

For example, many times I'll be editing code written by someone else, which is not commented, but I'll add commenting to my own work. I wouldn't want that to end up falling through.

Perhaps you could include some sort of "inherit" tag, which could then specify the field/method/class/whatever to inherit the docs from?

Daniel Siegmann wrote:
> Walter wrote:
> 
>>> From that you can't tell if class D is documented for real, or just been
>>> forgotten. That's a problem because compiler should falsely use the
> 
> <snip>
> 
>> The reason I put it in like that is sometimes one documents as a group a set
>> of related functions, such as:
>>
>>     float sin(float)
>>     double sin(double)
>>     real sin(real)
>>
>> and it's just feels stupid to have to separately document them with
>> cut/paste. I understand the problem you're describing, though, and I don't
>> see a solution to it other than "don't do that" :-(
> 
> 
> I really don't like comments falling through. Much better to give some way to explicitly inherit a comment from something else.
> 
> For example, many times I'll be editing code written by someone else, which is not commented, but I'll add commenting to my own work. I wouldn't want that to end up falling through.
> 
> Perhaps you could include some sort of "inherit" tag, which could then specify the field/method/class/whatever to inherit the docs from?

Wouldn't something like this be so much simpler?
#  /** sin functions
#   * Some kind of description.
#   * {
#   */
#  float  sin (in float  x) { ... }
#  double sin (in double x) { ... }
#  real   sin (in real   x) { ... }
#  /**
#   * }
#   */

Or.
#  /// sin functions
#  /// Some kind of description.
#  /// {
#  float  sin (in float  x) { ... }
#  double sin (in double x) { ... }
#  real   sin (in real   x) { ... }
#  /// }

-- Chris Sauls

Ben Hinkle wrote:
<snip>
> @because @human-readable @text @doesn't @have @ats @in @it

So whenever you insert an email address in a bit of text, humans cease to be able to read it?

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:
> "Knud Sørensen" <12tkvvb02@sneakemail.com> wrote in message
> news:pan.2005.08.31.09.46.08.415427@sneakemail.com...
>> What I am missing is a way to add the unit test to the
>> documentation as examples.
>>
>> Most auto-generated documents doesn't have enough examples.
> 
> True, but unit tests generally make for poor examples.

But they don't have to!  Someone can write unittests that make good examples.  As well as, not instead of, typical unittests that are designed to check that the code is working in a number of cases and not as a demonstration of how to use the library.

The programmer would insert a documentation comment to indicate that a unittest is to be documented as an example.

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.

Of course, at the basic level of this feature, the assert statements would show up in the example, and this may or may not be what one wants.    Even if we provide an option to strip assert statements from the documentation, there might be leftover for loops that did nothing but an assert on each element of an array in turn, or even other statements that don't really belong to the example but are solely to prepare data to assert against.  Maybe we should have a comment form to mark the end of an example or a section that should be excluded from the example.

Conversely, not all examples make good unittests.  For example, code that writes to a file or implements a GUI might not be desirable to write as a unittest.  And so we should also be able to include an example by putting it into the code as a comment or by referencing another code file.

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

"#  It should be possible for the user to use Doxygen or other
documentation extractor if desired."

Do you mean that Doxygen supports this comment style now?  Or that it should degrade into something reasonable?  ISTM you'd need blank lines in places, otherwise you'd get stuff awkwardly run together like

This is my function. Params: fp File pointer name File name and more.

"int x,  // is for this"

Should this be /// rather than // ?

"HTML can be embedded into the documentation comments, and it will be passed through to the HTML output unchanged. However, since it is not necessarilly true that HTML will be the desired output format of the embedded documentation comment extractor, it is best to avoid using it where practical."

It ought to be specified that HTML character entities, at least < > & 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.

And will there be a way to group members into sections, as there is with Doxygen?

Spelling corrections:
liklihood -> likelihood
necessarilly -> necessarily

(Knowing you, s/illy/ily would make a half-decent spellchecker! :-) )

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.

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.

-- 
Derek Parnell
Melbourne, Australia
2/09/2005 11:51:11 PM

On Fri, 02 Sep 2005 13:04:07 +0100, Stewart Gordon wrote:

> Ben Hinkle wrote:
> <snip>
>> @because @human-readable @text @doesn't @have @ats @in @it
> 
> So whenever you insert an email address in a bit of text, humans cease to be able to read it?

I suspect you have gone to an extreme that is not reasonable. An email address has one '@' symbol, whereas the example line has many such symbols. Your point is discounted.

-- 
Derek Parnell
Melbourne, Australia
2/09/2005 11:53:37 PM

"Stewart Gordon" <smjg_1998@yahoo.com> wrote in message news:df9keh$kvi$1@digitaldaemon.com...
> Walter wrote:
> > I've put up a strawman proposal for embedding documentation in comments
at
> > www.digitalmars.com/d/doc.html
> "#  It should be possible for the user to use Doxygen or other documentation extractor if desired."
>
> Do you mean that Doxygen supports this comment style now?  Or that it should degrade into something reasonable?  ISTM you'd need blank lines in places, otherwise you'd get stuff awkwardly run together like

No, what I mean is that the Ddoc stuff is completely optional on the part of the programmer. Comments will be ignored by the compiler, which means that any documentation system that relies on embedded documentation comments can be used and can use their entirely unique, and incompatible, format.

> This is my function. Params: fp File pointer name File name and more.
>
> "int x,  // is for this"
>
> Should this be /// rather than // ?

Yes.

> "HTML can be embedded into the documentation comments, and it will be passed through to the HTML output unchanged. However, since it is not necessarilly true that HTML will be the desired output format of the embedded documentation comment extractor, it is best to avoid using it where practical."
>
> 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.

> And will there be a way to group members into sections, as there is with Doxygen?

Not in the first version. Ddoc isn't as advanced as Doxygen, and probably won't become so.

>
> Spelling corrections:
> liklihood -> likelihood
> necessarilly -> necessarily

Got it, thanks!