svn commit: r210225 - in head/sys: kern sys

[Bruce Evans]

On Sun, 18 Jul 2010, Colin Percival wrote:

> On 07/18/10 13:23, Edward Tomasz Napierala wrote:
>> Log:
>>   The "/*-" comment marker is supposed to denote copyrights.  Remove non-copyright
>>   occurences from sys/sys/ and sys/kern/.
>
> The "/*-" comment marker indicates to utilities that comments should not be
> re-wrapped.  Some of the comments you've changed would distinctly suffer if
> they were re-wrapped, e.g.,

Indeed, the use of this marker for copyright comments is secondary:

- most copyright comments would be mangled if they were re-wrapped.  Thus
   ones that don't have the marker are usually wrong.  There is an
   alternative marker "/**" (see indent(1)).  Use of this would be just
   a style bug.  Use of full box comments (with comments ornated in
   boxes made of mostly "*"'s or possibly hyphens or bars or even
   terminal-specific box drawing characters) would be a larger style
   bug.  indent(1) only claims to support these markers in connection
   with supporting full box comments.

- someone made copyright comments easier to find by using this marker for
   them constently.

>> -/*-
>> +/*
>>   * Change a process's real uid.
>>   * Side effects: newcred->cr_ruid will be updated, newcred->cr_ruidinfo
>>   *               will be updated, and the old and new cr_ruidinfo proc
>
> If you don't want to have "/*-" for these, please change them instead to
> "/**", since that is an alternative "box comment" marker.

Ugh, please don't do this.  I want to have "/*-" for normal (but
intricately formatted) block comments.  Most files should have probably
have more of these than copyright comments.  However, many intricately
formatted block comments are missing the marker.  I added the -nfcb
flag to indent(1) for avoiding mangling of any block comment, and use
it in my .indent.pro, so I rarely see this mangling.

The "/**" marker is already used to make doxygen markup especially ugly.
I don't know if this is part of the doxygen markup or of the "@foo"
markup does everything.

Bruce