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