← Back to team overview

kicad-developers team mailing list archive

Redundancy in doc comments

 

Hi all and mostly Wayne,

I notice that a lot of our older documentation comments redundantly list
the name of the function they document:

    /**
     * Function IsVoid
     * @return true if the field value is void (no text in this field)
     */
    bool IsVoid() const

I don't see any purpose for this redundancy - Doxygen doesn't use it,
the formatted documentation actually looks better without it. It seems
unnecessary to me, and a bit ugly: https://misc.c4757p.com/isvoid.png

(Not to mention that this is a method, not a function ;)

I'd document this method thus:

    /**
     * @return true iff the field value is void (i.e. has no text)
     */
    bool IsVoid() const

Is there any reason to keep these?

-- 
Chris


Follow ups