llvm dev - Oct 2012 - [LLVMdev] Duplicating routine/class name in documentation comment.

I understand that current coding guidelines are strictly against
duplicating routine/class name in documentation comment though old
code is written that way, but, I could still see this kind of
duplication in few recent check-ins, after I got this review comment
for one of my recent patches. So, I am curious to send this mail.


-- 
mahesha

On Tue, Oct 30, 2012 at 3:02 PM, Mahesha HS <mahesha.llvm at gmail.com>
wrote:
> I understand that current coding guidelines are strictly against
> duplicating routine/class name in documentation comment though old
> code is written that way, but, I could still see this kind of
> duplication in few recent check-ins, after I got this review comment
> for one of my recent patches. So, I am curious to send this mail.
>
>
> --
> mahesha
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
>
It is generally discouraged because duplication causes documentation to go
out of date whenever the function/class name changes: it's a drag to
remember to update the comment and many times people don't.

Instead, it's simply easier to let Doxygen correctly assess which
class/function the comment targets. It just works!

-- Matthieu
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.llvm.org/pipermail/llvm-dev/attachments/20121030/731051f8/attachment.html>

On Tue, Oct 30, 2012 at 7:02 AM, Mahesha HS <mahesha.llvm at gmail.com>
wrote:
> I understand that current coding guidelines are strictly against
> duplicating routine/class name in documentation comment though old
> code is written that way, but, I could still see this kind of
> duplication in few recent check-ins, after I got this review comment
> for one of my recent patches. So, I am curious to send this mail.
Essentially, old habits die hard. ;]

It will take time for those with long-established habits of writing
doxygen comments to retrain themselves, and some code even though it
is submitted recently, dates from before the rule went into effect.

That said, if you see code getting submitted with this style of
doxygen comment, feel free to leave a note to remind the author to
clean it up in favor of newly advised comment style.
>
>
> --
> mahesha
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits