Date: Mon, 19 Jul 2010 13:41:59 +1000 (EST) From: Bruce Evans <brde@optusnet.com.au> To: Colin Percival <cperciva@FreeBSD.org> Cc: svn-src-head@FreeBSD.org, svn-src-all@FreeBSD.org, src-committers@FreeBSD.org, Edward Tomasz Napierala <trasz@FreeBSD.org> Subject: Re: svn commit: r210225 - in head/sys: kern sys Message-ID: <20100719132004.B5329@delplex.bde.org> In-Reply-To: <4C436535.7000000@freebsd.org> References: <201007182023.o6IKNBaU052215@svn.freebsd.org> <4C436535.7000000@freebsd.org>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20100719132004.B5329>