Comment by WalterBright
2 years ago
I don't expect to attain it, which is why I remarked on it as a goal. I've discovered that a lot can be done to eliminate the need for some forms of documentation. Also a lot can be done with the language to make it more expressive, and thus eliminating the need to document something.
For example, having the parameter to a function declared `const` means the function cannot alter it, and this is checked by the compiler. It won't be necessary to mention that in the function documentation.
P.S. This doesn't work in C and C++, despite them having a `const` type qualifier. This is because the `const` is not transitive, and can be legitimately cast away. Therefore, it's useless as a guarantee. D's `const` is transitive, and although you can cast it away in @system code, you're on your own with that.
> For example, having the parameter to a function declared `const` means the function cannot alter it, and this is checked by the compiler. It won't be necessary to mention that in the function documentation.
Actually you should mention it in the documentation. There's 2 types of documentation, so it's easier to just do the one: documentation for users, documentation for developers. Unless you work absolutely alone on all your projects and you don't open source them, someone else is going to be reading your code.
Why should the documentation repeat that a pointer to const cannot modify what it is pointing to?
> Why should the documentation
>> someone else is going to be reading your code.
Someone else is going to {read,edit,write,maintain} your code. Which means __anything__ the code does should be explained. Before you were suggesting documentation is only for the user. Documentation is also important for the developer. Whoever takes over your code later or works on it with you.
2 replies →