Undocumented API improvements

[guwirth]

We were introducing the Undocumented API metric in our company. I got the following feedback from the developers:

• Feature does not support inherited documentations like doxygen with the switch INHERIT_DOCS. There it is possible to document an API only in the interface or base class. Developers don't want to maintain (same) comments at two places.
• Typically it makes less sense to document default ctor and default dtor. There should be a switch to suppress messages for such methods.
• Typically it makes less sense to document operators (=, +, -, ...) the meaning is normally clear. Only if a operator behaves different they should be documented.
• Getter and Setter: Should be sufficient to document corresponding member variable. Setter is setting it and getter is returning the current value.

What is your experience with the feature?

[lcintrat]

Very interesting feedback!

• For the inherited documentation, IMHO, this is a complex feature. Another approach would be to use the @copydoc tag.
• For default ctor, default dtor and operators, I agree with switch approach.
• For Getter and Setter, this seems feasible, with a switch to enable the feature.

[francoisferrand]

Hello,

I fully agree with the first 3 items, though first one will ne difficult to do precisely. Maybe one simple filter could be to watch for the "override" keyword.

Regarding the last item, I disagree : we are talking about documenting the API, so there is no point speaking about the documentation of member variables (which in most case are private).

Sure, as a developer it is tempting to say this is just the doc of he variable, but it is incomplete (there are often conditions, eg the setter may not work immediately or must be called at the right time), but mostly it means documenting the implementation (which will change) instead of the API (which should hopefully not change).

Regards,

On 21 janv. 2016, at 10:00, Günter Wirth [email protected] wrote:

We were introducing the Undocumented API metric in our company. I got the following feedback from the developers:

Feature does not support inherited documentations like doxygen with the switch INHERIT_DOCS. There it is possible to document an API only in the interface or base class. Developers don't want to maintain (same) comments at two places.
Typically it makes less sense to document default ctor and default dtor. There should be a switch to suppress messages for such methods.
Typically it makes less sense to document operators (=, +, -, ...) the meaning is normally clear. Only if a operator behaves different they should be documented.
Getter and Setter: Should be sufficient to document corresponding member variable. Setter is setting it and getter is returning the current value.
What is your experience with the feature?

—
Reply to this email directly or view it on GitHub.

[guwirth]

• inherited documentation: I like the idea with the override as marker for derived documentation. Seems to be also easy to implement?
• getter/setter: maybe typez is right. But looking in reviews the comments are mostly very stupid: Get .... / Set .... . Thinking about this it could also be very difficult to detect which variable belongs to a setter/getter. Depending on naming convention variable name could be m_xxx or xxx_ or ... . So I agree we should not do it.

[guwirth]

@lcintrat do you have some time for enhancements?

[lcintrat]

Finally, there is only the override feature to add?
Should not take long to implement. I don't have much time, but I will try.

[guwirth]

Think that is the most important one.

Am 01.02.2016 um 10:28 schrieb Ludovic Cintrat [email protected]:

Finally, there is only the override feature to add?
Should not take long to implement. I don't have much time, but I will try.

—
Reply to this email directly or view it on GitHub.

[guwirth]

@lcintrat like to ask if you have some time for the override feature?

[lcintrat]

Hi @guwirth

I can do it this week.

[guwirth]

@lcintrat thanks. Good to know.