Hacker News new | ask | show | jobs
by bruceboughton 4939 days ago
If you're using auto-doc-generation, there is no information in the generated documentation that isn't in the API.
1 comments

Not sure what you mean by "the API". You mean C# interfaces? And what about Intellisense?
Intellisense is generated from the types, methods, fields, and properties (the API). If there is XML documentation it is added to Intellisense popup. If the documentation is auto-generated from the code structure then it will add nothing that is not already present in the Intellisense.
Sure. Like I said, there are some cases where the textual documentation adds nothing to the stuff it's derived from. And there are lots of cases where documentation is useful (I'm assuming you're not saying there should be no documentation). I think that it's worth having consistency of rules (with some redundancy) over patchy documentation. I'm not trying to convince anyone, just a datapoint that I don't think it's "insane".
The original point was that auto-generated documentation comments contain nothing that isn't already there in the public interface. Since it tends to look like

    /**
     * Foos the bar.
     *
     * @param bar The bar.
     */
    public void fooBar(Bar bar) { ... }
The problem with this kind is that the compiler can no longer warn about a missing documentation comment because from its side all looks nice and well – except that there is zero information in that documentation.

My boss once did that to our entire codebase, adding auto-generated doc comments where there weren't any. Sure, my warning count reached a new low, but documentation quality suffered for months.