On Wednesday, 15 June 2016 at 00:16:12 UTC, Walter Bright wrote:
Overall, I find the documentation to be unusually good. Nice
work!
Thanks. :-D
================================================
.noex
The .noex member is oddly named, being a negative and no idea
what 'ex' means. It sets a sticky flag on error, so perhaps
.sticky?
Originally I wanted to have the policies just be `throws` and
`nothrow` - but of course `nothrow` is a keyword, so I chose
`noex` (short for "no exceptions") instead. I agree it looks kind
of odd though, especially since I later added the `asserts`
policy.
I'll consider renaming `noex`, or at least add an explanation of
the mnemonic to the docs.
---
N is a basic integral type, it needs a better name than 'N'.
How about 'BaseType' or even 'BaseIntegralType'? A complete
list of what types are acceptable for 'N' would be desirous,
too.
`N` is not a public symbol, and it's used all over the place. Do
I really need to give it some giant multi-word name?
Besides which, Phobos uses single-letter names for template
parameter type names all over the place.
---
'bscal' is a complete mystery without reading the
documentation. Perhaps 'value' instead?
`value` is a very popular name for function parameters and local
variables. `bscal` needs a more obscure name to prevent the free
function version (a shim to facilitate uniform treatment of basic
integral types and checkedint types in generic code) from
shadowing or being shadowed by local symbols.
(I originally called it `value`, but changed it once I realized
how annoying it is not to be able to use that name for anything
else in generic code that uses `checkedint`.)
Also, I prefer a more unfriendly name for `bscal` to remind
people that accessing it entails giving up all of the safety
benefits of `checkedint`. The fact that it's grep-able, too,
could be helpful to linters and the like.
---
enum IntFlagPolicy policy;
Should contain a link to the complete explanation.
---
Should have a "References:" section with link to core.checkedint
---
-O (DMD) should be a link to the -O flag instructions
http://dlang.org/dmd-windows.html#switch-O
---
'--inline' is not a DMD switch
---
Remove all use of 'you' and 'your' from the documentation. For
example:
"If you really need more speed, try switching to DebugInt for
the hottest code in your program (like inner loops) before
giving up on checkedint entirely."
becomes:
"For more speed, switch to DebugInt for the hottest code in the
program (like inner loops)."
(The internal link to DebugInt is wrong.)
And:
"This way, you can use SafeInt!N to debug your integer logic in
testing, but switch to basic N in release mode for maximum
speed and the smallest binaries."
becomes:
"This way, use SafeInt!N to debug integer logic in testing, but
switch to basic N in release mode for maximum speed and the
smallest binaries."
Reference material should never contain "you" or "your".
---
"debuggin" => "debugging"
---
There's an overall lack of use of internal links to navigate
within the page.
I will work on the docs some more.
---
Functions are tagged @safe. Are there any unsafe functions?
Sort of. There are a small number of template functions in
`checkedint` that call some outside function whose @safety is
unspecified, requiring the @safe-ty of the `checkedint` function
to be inferred.
I believe the complete list currently is:
* SmartInt.toString(sink, fmt)
* SafeInt.toString(sink, fmt)
* checkedint.to()
* IntFlag.toString(sink, fmt)
* IntFlags.toString(sink, fmt)
(It would be great if we could fill in the gaps in D's attribute
system - it's kind of ridiculous that for every attribute, there
is at least one possible mode that cannot be indicated explicitly
in any way.)
