From owner-svn-src-all@FreeBSD.ORG Mon Jul 19 03:42:04 2010 Return-Path: Delivered-To: svn-src-all@FreeBSD.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34]) by hub.freebsd.org (Postfix) with ESMTP id 6A75B1065670; Mon, 19 Jul 2010 03:42:04 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail08.syd.optusnet.com.au (mail08.syd.optusnet.com.au [211.29.132.189]) by mx1.freebsd.org (Postfix) with ESMTP id 02FB38FC17; Mon, 19 Jul 2010 03:42:03 +0000 (UTC) Received: from c122-106-145-25.carlnfd1.nsw.optusnet.com.au (c122-106-145-25.carlnfd1.nsw.optusnet.com.au [122.106.145.25]) by mail08.syd.optusnet.com.au (8.13.1/8.13.1) with ESMTP id o6J3fx2x001912 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 19 Jul 2010 13:42:01 +1000 Date: Mon, 19 Jul 2010 13:41:59 +1000 (EST) From: Bruce Evans X-X-Sender: bde@delplex.bde.org To: Colin Percival In-Reply-To: <4C436535.7000000@freebsd.org> Message-ID: <20100719132004.B5329@delplex.bde.org> References: <201007182023.o6IKNBaU052215@svn.freebsd.org> <4C436535.7000000@freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed Cc: svn-src-head@FreeBSD.org, svn-src-all@FreeBSD.org, src-committers@FreeBSD.org, Edward Tomasz Napierala Subject: Re: svn commit: r210225 - in head/sys: kern sys X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Jul 2010 03:42:04 -0000 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