dfmt options

[Idan Arye via Digitalmars-d]

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.