[OpenJDK Rasterizer] Marlin renderer contribution for review

[Jim Graham]

On 3/25/15 2:39 PM, Laurent Bourgès wrote:
>> Also, the very first file I brought up still had /** */ single line faux-doc comments (AAShapePipe, on private fields no less).  That was the second thing you said that you fixed below...?
>
> I disagree: this is a typical javadoc comment for a field (even
> private). Maybe you dislike javadoc for fields.
> What's clearly the problem ? Do you want me to remove all new comments /
> javadoc ?

I absolutely do not want you to delete the comments.  The content of the 
comments are important.

This is a minor style note and there is no functional flaw, but use of 
the "/**" format for these comments is inappropriate and out of place 
for internal code like this.  "/**" implies:

- we are going to run javadoc on this code (we aren't)
- the output of javadoc will be published somewhere (it won't)
- the comment adheres to much higher standards of content, including:
     - use of full sentences (most if all of these are sentence fragments)
     - use of recommended grammar and verb tenses as per the doc writer 
guidelines
     - proper annotations like @since and @see where appropriate
     - does the text of the comment promise something we don't want to 
guarantee?
     - does the text of the comment mention specific caveats we need to 
communicate?

You may believe that these are "typical javadoc comments for a field", 
but "/** dirty aabox array */" would never pass muster if we were 
planning on actually publishing these comments.

It's like talking to one of your siblings in a casual setting and yet 
using their full formal name and title.  There's nothing wrong with it, 
but it takes one out of the context and for just a second they wonder 
"are they about to reprimand me?  Oh, no, they're just being oddly 
formal..."

I would just use the "//" notation for these comments...

			...jim