From owner-svn-src-all@freebsd.org Thu Mar 16 04:00:24 2017 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id DCC25D0E773; Thu, 16 Mar 2017 04:00:24 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from mail107.syd.optusnet.com.au (mail107.syd.optusnet.com.au [211.29.132.53]) by mx1.freebsd.org (Postfix) with ESMTP id 60A571E17; Thu, 16 Mar 2017 04:00:23 +0000 (UTC) (envelope-from brde@optusnet.com.au) Received: from besplex.bde.org (c122-106-153-191.carlnfd1.nsw.optusnet.com.au [122.106.153.191]) by mail107.syd.optusnet.com.au (Postfix) with ESMTPS id C08D3D42D30; Thu, 16 Mar 2017 15:00:15 +1100 (AEDT) Date: Thu, 16 Mar 2017 15:00:14 +1100 (EST) From: Bruce Evans X-X-Sender: bde@besplex.bde.org To: Ngie Cooper cc: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: Re: svn commit: r315365 - head/lib/libkvm In-Reply-To: <201703160324.v2G3OFHh004812@repo.freebsd.org> Message-ID: <20170316144923.O1839@besplex.bde.org> References: <201703160324.v2G3OFHh004812@repo.freebsd.org> MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII; format=flowed X-Optus-CM-Score: 0 X-Optus-CM-Analysis: v=2.2 cv=VbSHBBh9 c=1 sm=1 tr=0 a=Tj3pCpwHnMupdyZSltBt7Q==:117 a=Tj3pCpwHnMupdyZSltBt7Q==:17 a=kj9zAlcOel0A:10 a=DiyqzgTmKoGjrKZWp48A:9 a=CjuIK1q_8ugA:10 X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.23 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: Thu, 16 Mar 2017 04:00:25 -0000 On Thu, 16 Mar 2017, Ngie Cooper wrote: > Log: > Tweak r315363 slightly > > I noticed after commit that kvm_dpcpu_setcpu was defined in the manpage. > Thus, the correct macro for the function reference is .Fn, not .Xr. Is .Xr ever correct for a function? I think it names man pages, not functions, and only the higher-quality man pages document only 1 function and have the same name as that function. Rendering might be different for function. I don't like generic .Xr's. They often point to very large man pages with relevant 1 clause in sentence, and no hint about what this clause might say or how to find it. Generic .Xr's are typically found in the main .Xr section, with no hints about how they are relevant to the current man page either. Ones in other sections at least have some nearby context. Naming functions in other pages is actually more useful than naming the man page containing them. Then you can grep for clauses containing the function name. Bruce