Improve destroy's documentation #2054
Conversation
|
Thanks for your pull request, @JinShil! Bugzilla referencesYour PR doesn't reference any Bugzilla issue. If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog. |
src/object.d
Outdated
| destroy(i); | ||
| assert(i == 0); // `i` is back to its initial state `0` | ||
| } | ||
| ---- |
There was a problem hiding this comment.
Why don't you use a ddoc-ed unittest (or multiple)?
/// reference type demonstration
unittest
{
}
/// value type demonstration
unittest
{
}They have the advantage of being
- checked by the testsuite -> guaranteed the code will work in the future
- runnable by the reader
There was a problem hiding this comment.
Changed example to unittest blocks. I hope that's what you meant.
There was a problem hiding this comment.
Nope it's not. You are still having it as a comment. I added a commit with what I meant.
Ddoc-ed unittest start with /// (or /++, /**) and will be part of the documentation, see e.g.
| does is done and so that it no longer references any other objects. It does | ||
| $(I not) initiate a GC cycle or free any GC memory. | ||
| +/ | ||
| /******** |
There was a problem hiding this comment.
We really need to define a best practice for docstrings.
Generally I'm a fan of using only as many * / + as strictly necessary:
/++
+/
or
/**
*/
There was a problem hiding this comment.
Same here. Not a fan of lots of stars or stars at the beginning of each comment line.
There was a problem hiding this comment.
I was following @andralex's prior suggestion here: dlang/dmd#6835 (comment)
Let's use https://github.com/dlang/phobos/blob/master/std/string.d#L2254-L2267 for new code, thanks.
Anyway, if it's important, please make a PR to the style guide with preferred dos and don'ts
The current documentation for
destroysays that it sets the object to an "invalid state", but that's not what I've found in my testing, so I changed the documentation to explain what I think is happening, and added an example for illustration.