Open schveiguy opened 7 years ago
Generally seems like a reasonable approach. I'd just only use the section's contents without the "Returns " prefix, because there are various styles in which these sections are typically written. Another problem is that the "Returns:" section, like most sections allows to write multiple paragraphs, but the short description is just a single one (and a particularly short one), so it would have to be the first paragraph of the section that is used.
Of course one could simply use /// The property value
instead of /// Returns: The property value
, too, without really losing anything. But handling existing Ddoc targeted code as well as possible still makes sense.
I think it is good for automated systems to have the Returns
section filled out if it returns something. I remember getting dinged by Walter for things like this.
Consider a property function:
In the ddox overview, it shows a blank description for this method. In order to get a description to show up, I need to essentially repeat the Returns section. It would be nice if ddox noticed a missing description and used
Returns <return description>
if there is one.