[cfe-commits] r171013 - /cfe/trunk/lib/CodeGen/CGDecl.cpp

[John McCall]

On Jan 3, 2013, at 5:10 PM, Dmitri Gribenko <gribozavr at gmail.com> wrote:
> On Fri, Jan 4, 2013 at 2:58 AM, John McCall <rjmccall at apple.com> wrote:
>> On Dec 23, 2012, at 5:48 PM, NAKAMURA Takumi <geek4civic at gmail.com> wrote:
>>> Author: chapuni
>>> Date: Sun Dec 23 19:48:59 2012
>>> New Revision: 171013
>>> 
>>> URL: http://llvm.org/viewvc/llvm-project?rev=171013&view=rev
>>> Log:
>>> CGDecl.cpp: Prune three descriptions in two methods, CodeGenFunction::pushIrregularPartialArrayCleanup() and CodeGenFunction::pushRegularPartialArrayCleanup(). [-Wdocumentation]
>>> 
>>> /// \param array - a value of type elementType*
>>> /// \param destructionKind - the kind of destruction required
>>> /// \param initializedElementCount - a value of type size_t* holding the number of successfully-constructed elements
>> 
>> Wait, why are you pruning these?  Other than destructionKind, this is all valuable documentation.
> 
> The issue is that there are no parameters named 'array',
> 'destructionKind' and 'initializedElementCount' in the function, thus
> -Wdocumentation was complaining.

Ah, I see.  The problem is that I converted this API to take a begin/end
pair rather than a begin/count pair.

>> When documentation in IR-generation talks about the type of a parameter, it's generally not repeating information from the C++ type system;  it's talking about the type *of an abstract value*.  That is, initializedElementCount is (in C++) just an llvm::Value*, but the documentation is clarifying that that llvm::Value* must have LLVM IR type size_t*, i.e. i32* or i64*.
> 
> I am sorry that valuable documentation was pruned.  We would
> appreciate if you could update this comment when llvm.org goes up.

I don't mind updating the documentation.  However, it is not really
appropriate to delete non-redundant documentation just because
(1) it's malformed in some way and (2) it's not immediately obvious
to you how to fix it.  You need to be pinging the original authors (or,
failing that, the code owners) and asking for guidance.

Please review your recent changes, restore any similar documentation
that you've purged, and ping the authors.

John.