<div class="gmail_extra"><div class="gmail_quote">On Fri, Sep 14, 2012 at 11:12 AM, Andrew Trick <span dir="ltr"><<a href="mailto:atrick@apple.com" target="_blank" class="cremed">atrick@apple.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im"><br>
On Sep 14, 2012, at 10:44 AM, Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com" class="cremed">gribozavr@gmail.com</a>> wrote:<br>
<br>
> On Fri, Sep 14, 2012 at 8:32 PM, Andrew Trick <<a href="mailto:atrick@apple.com" class="cremed">atrick@apple.com</a>> wrote:<br>
>><br>
>> On Sep 14, 2012, at 8:27 AM, Dmitri Gribenko <<a href="mailto:gribozavr@gmail.com" class="cremed">gribozavr@gmail.com</a>> wrote:<br>
>><br>
>>> Hello,<br>
>>><br>
>>> @Chris, Chandler: CC'ing you since this an addition to the policies<br>
>>> and I feel like I need your review.<br>
>>><br>
>>> The attached patch documents current Doxygen use practices in Coding<br>
>>> Standards.  Mostly it is obvious stuff and most new code being<br>
>>> committed conforms to that.  Some old code does not; this might cause<br>
>>> confusion and this is the motivation to document the correct<br>
>>> guidelines.<br>
>>><br>
>>> Please review.<br>
>><br>
>> +Don't duplicate the documentation comment in header file and in implementation<br>
>> +file.  If the API being documented is not module-private, documentation should<br>
>> +go to the header file.<br>
>><br>
>> Sorry, this wasn't obvious to me, so I may be violating it in the short term until I understand the policy.<br>
><br>
> This is to document the current practice rather than to introduce<br>
> something new, so I brought it up for discussion.<br>
><br>
>> I'm definitely going to add function-level comments in the .cpp file. So should those detailed comments be doxygen style? The header comments are for people who need to understand the API. The out-of-line comments are for people hacking on the implementation. I often start by duplicating the short comment and refine it from there.<br>

><br>
> I didn't really understand you.  Do you mean that for a given function<br>
> you put interface explanations in .h and implementation comments in<br>
> .cpp right before the function?  It would be nice if you could give a<br>
> pointer to some example.<br>
<br>
<br>
</div><MachineScheduler.h><br>
<br>
  /// Implement ScheduleDAGInstrs interface for scheduling a sequence of<br>
  /// reorderable instructions.<br>
  virtual void schedule();<br>
<br>
<MachineScheduler.cpp><br>
<br>
/// schedule - Called back from MachineScheduler::runOnMachineFunction<br>
/// after setting up the current scheduling region. [RegionBegin, RegionEnd)<br>
/// only includes instructions that have DAG nodes, not scheduling boundaries.<br>
///<br>
/// This is a skeletal driver, with all the functionality pushed into helpers,<br>
/// so that it can be easilly extended by experimental schedulers. Generally,<br>
/// implementing MachineSchedStrategy should be sufficient to implement a new<br>
/// scheduling algorithm. However, if a scheduler further subclasses<br>
/// ScheduleDAGMI then it will want to override this virtual method in order to<br>
/// update any specialized state.<br>
void ScheduleDAGMI::schedule()<br>
<br>
I admit that most of the time I just duplicate the short comment and have nothing more to say. It's nice to have a place to tack on FIXME's and TODO's though.<br></blockquote><div><br></div><div>I'm actually very comfortable with the only comments on a function's implementation being FIXME and TODO entries... =] More comfortable if they decrease over time.</div>
<div><br></div><div>I'm also very comfortable with functions whose implementation is blindingly obvious to the reader, and there is really nothing to say, having no comment in the source code. We shouldn't add comments just to have that block of text at the top. ;]</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<br>
I never realized that duplicating the short comment was a problem. It's no more irritating to update than the function name and type, though less often caught. It seems by Chandler's logic we should omit variable names from the function prototype too.<br>
</blockquote><div><br></div><div>I wouldn't go that far. The names in the prototype help serve as part of the documentation, and in fact allow writing much of the doxygen interface comments. Omitting them would be counterproductive in that since.</div>
<div><br></div><div>Also, for whatever reason, I've heard almost no complaints about these getting out of sync (whether or not it happens). I don't have any real logical argument as to why, but that's the observation I make from watching the development and listening to quite a few new developers ramping up.</div>
</div></div>