[Issue 6232] And idea for std.string.toStringz docs

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=6232



--- Comment #2 from bearophile_hugs at eml.cc 2011-06-30 18:18:46 PDT ---
(In reply to comment #1)
> That's a lot to add to the documentation for something which is completely
> unnecessary to use or understand the function.

Good documentation must show non-obvious but important usages of the functions
too. See below.


> And it would only make sense if
> it were considered best practice to do this, and I think that you're going to
> have a hard time convincing people that they should do this in the general
> case. The typical thing to do with toStringz is to just pass the result
> directly to a C function and be done with it. Your suggestion is completely
> overkill in such cases.

This suggestion of mine may be wrong, ad surely there are ways to improve it
(in the name I've used too). But so far in D.learn I've seen three times people
talk about bugs coming from not passing zero terminated strings to C functions.
toStringz solves the problem, but you have to remember to use it in the first
place.

Languages with good type systems like Haskell, F#, ATS, etc show that tons of
bugs are avoidable using type systems in a smarter way. D type system isn't as
refined as Haskell or Scala one, but it's good enough, if used well, to avoid
many C-string bugs.


> This is an enhancement request, so I'm not going to just close it, but I really
> don't think that anything like this should be in the documentation. A
> function's documentation is for explaining what a function does and how its
> used, not for stuff like this.

This example shows how to use D type system and toStringz. Tricks and smart
usages are at the right place in docs. Delphi documentation shows this well.

Another example are the itertools recipes present in the docs only:
http://docs.python.org/library/itertools.html#recipes


> This sort of thing would only make sense if
> CcharPtr and tostringz2 were actually added to Phobos, in which case, the
> documentation would go on _them_, not toStringz.

This is probably not going to happen, Walter doesn't want "swallow" functions
in Phobos. So they need to go in lists of "recipes" or examples in the docs.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------