std.experimental.checkedint is ready for comments!

[tsbockman via Digitalmars-d]

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.)