www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - Trivial doc error in %g format.

reply Don Clugston <dac nospam.com.au> writes:
in std_format.html:

under 'g','G':

"The Precision specifies the number of significant digits, and defaults 
to one."

Actually it defaults to six. Presumably this is just a typo.

BTW, based on what other people are doing, I'm assuming that 
documentation errors should only go into the ng, not into Bugzilla. Is 
this correct?

(If Bugzilla, I think that there should be a seperate category for doc 
errors. By definition, they are never OS/Platform dependent, and they 
shouldn't normally appear in the changelog. Or should they always be 
entered as trivial?)
Mar 20 2006
parent reply jcc7 <jcc7_member pathlink.com> writes:
In article <dvm7a3$2knd$1 digitaldaemon.com>, Don Clugston says...

in std_format.html:

under 'g','G':

"The Precision specifies the number of significant digits, and defaults 
to one."

Actually it defaults to six. Presumably this is just a typo.

BTW, based on what other people are doing, I'm assuming that 
documentation errors should only go into the ng, not into Bugzilla. Is 
this correct?


I would usually just add a comment to the wiki page for something relatively
small like this, but we haven't been able to confirm how often Walter has time
to review the comments.

I went ahead and added a comment on this at 
http://www.prowiki.org/wiki4d/wiki.cgi?DocComments/Phobos/StdFormat since it
might be helpful for someone else down the line, and it gives Walter another
chance to see the error.

Also, I added an example since it wasn't clear to me what the problem was at
first (I figured it out eventually):
http://trac.dsource.org/projects/tutorials/wiki/WritefLnWithFloatExample


(If Bugzilla, I think that there should be a seperate category for doc 
errors. By definition, they are never OS/Platform dependent, and they 
shouldn't normally appear in the changelog. Or should they always be 
entered as trivial?)


Often, the problem is that you don't know if Walter intends it to work as
documented or as it's implemented. In this case, a default of 6 digits of
precision makes more sense to me, but perhaps the docs are correct and the code
is at fault. And when there's doubt whether the docs are the problem, it doesn't
have to be trivial.

On the other hand, a misspelled word or a run-on sentence that would be trivial
(and not too controversial). But I think those would be more appropriate for
just adding a comment to the wiki anyway.

jcc7
Mar 20 2006
parent reply Don Clugston <dac nospam.com.au> writes:
jcc7 wrote:

 In article <dvm7a3$2knd$1 digitaldaemon.com>, Don Clugston says...

 in std_format.html:

 under 'g','G':

 "The Precision specifies the number of significant digits, and defaults 
 to one."

 Actually it defaults to six. Presumably this is just a typo.

 BTW, based on what other people are doing, I'm assuming that 
 documentation errors should only go into the ng, not into Bugzilla. Is 
 this correct?


 
 I would usually just add a comment to the wiki page for something relatively
 small like this, but we haven't been able to confirm how often Walter has time
 to review the comments.
 
 I went ahead and added a comment on this at 
 http://www.prowiki.org/wiki4d/wiki.cgi?DocComments/Phobos/StdFormat since it
 might be helpful for someone else down the line, and it gives Walter another
 chance to see the error.
 
 Also, I added an example since it wasn't clear to me what the problem was at
 first (I figured it out eventually):
 http://trac.dsource.org/projects/tutorials/wiki/WritefLnWithFloatExample


Thanks.


 (If Bugzilla, I think that there should be a seperate category for doc 
 errors. By definition, they are never OS/Platform dependent, and they 
 shouldn't normally appear in the changelog. Or should they always be 
 entered as trivial?)


 
 Often, the problem is that you don't know if Walter intends it to work as
 documented or as it's implemented. In this case, a default of 6 digits of
 precision makes more sense to me, but perhaps the docs are correct and the code
 is at fault. And when there's doubt whether the docs are the problem, it
doesn't
 have to be trivial.


It's always 6 digits in C, one digit would be ridiculous. But point taken.


 On the other hand, a misspelled word or a run-on sentence that would be trivial
 (and not too controversial). But I think those would be more appropriate for
 just adding a comment to the wiki anyway.


I haven't seen much evidence that Walter ever reads the wiki <g>. It 
doesn't seem a good place for reporting bugs in the docs. (seems better 
for discussions of things within the D community).
Mar 21 2006
parent jcc7 <jcc7_member pathlink.com> writes:
In article <dvodda$2f6t$1 digitaldaemon.com>, Don Clugston says...

jcc7 wrote:

 In article <dvm7a3$2knd$1 digitaldaemon.com>, Don Clugston says...

 in std_format.html:

 under 'g','G':

 "The Precision specifies the number of significant digits, and defaults 
 to one."

 Actually it defaults to six. Presumably this is just a typo.

 BTW, based on what other people are doing, I'm assuming that 
 documentation errors should only go into the ng, not into Bugzilla. Is 
 this correct?


 
 I would usually just add a comment to the wiki page for something relatively
 small like this, but we haven't been able to confirm how often Walter has time
 to review the comments.
 
 I went ahead and added a comment on this at 
 http://www.prowiki.org/wiki4d/wiki.cgi?DocComments/Phobos/StdFormat since it
 might be helpful for someone else down the line, and it gives Walter another
 chance to see the error.
 
 Also, I added an example since it wasn't clear to me what the problem was at
 first (I figured it out eventually):
 http://trac.dsource.org/projects/tutorials/wiki/WritefLnWithFloatExample


Thanks.


You're welcome.


 (If Bugzilla, I think that there should be a seperate category for doc 
 errors. By definition, they are never OS/Platform dependent, and they 
 shouldn't normally appear in the changelog. Or should they always be 
 entered as trivial?)


 
 Often, the problem is that you don't know if Walter intends it to work as
 documented or as it's implemented. In this case, a default of 6 digits of
 precision makes more sense to me, but perhaps the docs are correct and the code
 is at fault. And when there's doubt whether the docs are the problem, it
doesn't
 have to be trivial.


It's always 6 digits in C, one digit would be ridiculous. But point taken.


I didn't know that was the case in C, so I agree it's probably just a typo.


 On the other hand, a misspelled word or a run-on sentence that would be trivial
 (and not too controversial). But I think those would be more appropriate for
 just adding a comment to the wiki anyway.


I haven't seen much evidence that Walter ever reads the wiki <g>. 


I've seen some evidence. At least a little. 

But at least the other users can benefit from seeing that they're not the only
one who's run into that problem or has that concern. The downside to only
reporting in the bug newsgroup is that problems can move from page 1 to page 10
fairly quickly (assuming that Walter doesn't fix it immediately). But maybe
using Bugzilla will mitigate this problem as it's much easier to search that the
newsgroups.


It doesn't seem a good place for reporting bugs in the docs. (seems better 
for discussions of things within the D community).


You might be right. I'm not convinced that the wiki is good for reporting
documentation bugs either. But it seemed like a good idea when we started it,
and I'm not certain I was wrong yet.

jcc7
Mar 21 2006