On Monday, 16 March 2015 at 00:13:58 UTC, Rikki Cattermole wrote:
On 16/03/2015 8:08 a.m., Walter Bright wrote:
On 3/14/2015 8:32 PM, Rikki Cattermole wrote:
This might be a bit of a out of scope, but auto generating of
DDOC
comments for
symbols would be nice. Basically to enforce before e.g.
committing that
everything has been explained.
Autogeneration of documentation is by definition useless.
Documentation
is for 'why' and 'how'. Autogeneration can never be more than
reformatted source code.
It is yes. No disagreement there.
Its just a real pain to create these stubs by hand. Atleast
this way, people will moan about documentation being empty and
it'll seem less work to do.
At any rate, that's not a job for a code formatter. Code
formatters should mess around with whitespace, maybe with comment
styles(e.g. fixing the border of multiline comments) - and that's
it. Adding comments it's way out of it's scope.
And if you need a more concrete reason - a code formatter should
be able to act as a filter - put code in STDIN, get formatted
code from STDOUT. So, let's say I mark the function without it's
docs, and send it to dfmt. Should dfmt add docs to it? The docs
are already there, but dfmt cannot tell because it only got the
function itself...
The traditional place to inject documentation stubs is in the
snippets engine - where it is acceptable to automatically add
code. And if want to check for missing docs, you can always use
dscanner
--styleCheck(https://github.com/Hackerpilot/Dscanner#style-check)
to find them, instead of relying on people to complain about them.
