From patchwork Tue Jun 23 10:50:24 2009 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 31951 Received: from vger.kernel.org (vger.kernel.org [209.132.176.167]) by demeter.kernel.org (8.14.2/8.14.2) with ESMTP id n5NAoVbD027172 for ; Tue, 23 Jun 2009 10:50:32 GMT Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1753168AbZFWKu1 (ORCPT ); Tue, 23 Jun 2009 06:50:27 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753916AbZFWKu1 (ORCPT ); Tue, 23 Jun 2009 06:50:27 -0400 Received: from mx2.redhat.com ([66.187.237.31]:38866 "EHLO mx2.redhat.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753168AbZFWKu0 (ORCPT ); Tue, 23 Jun 2009 06:50:26 -0400 Received: from int-mx2.corp.redhat.com (int-mx2.corp.redhat.com [172.16.27.26]) by mx2.redhat.com (8.13.8/8.13.8) with ESMTP id n5NAoSnj004411; Tue, 23 Jun 2009 06:50:28 -0400 Received: from ns3.rdu.redhat.com (ns3.rdu.redhat.com [10.11.255.199]) by int-mx2.corp.redhat.com (8.13.1/8.13.1) with ESMTP id n5NAoRNx023644; Tue, 23 Jun 2009 06:50:27 -0400 Received: from pedra.chehab.org (vpn-12-11.rdu.redhat.com [10.11.12.11]) by ns3.rdu.redhat.com (8.13.8/8.13.8) with ESMTP id n5NAoOqP020020; Tue, 23 Jun 2009 06:50:25 -0400 Date: Tue, 23 Jun 2009 07:50:24 -0300 From: Mauro Carvalho Chehab To: "Karicheri, Muralidharan" Cc: Hans Verkuil , "linux-media@vger.kernel.org" Subject: Re: [PULL] http://www.linuxtv.org/hg/~hverkuil/v4l-dvb-vpfe-cap Message-ID: <20090623075024.66ac5d70@pedra.chehab.org> In-Reply-To: References: <200906191439.14197.hverkuil@xs4all.nl> <20090621143311.1c93db2e@pedra.chehab.org> <200906212020.29866.hverkuil@xs4all.nl> <20090621153157.35fc2ee7@pedra.chehab.org> Mime-Version: 1.0 X-Scanned-By: MIMEDefang 2.58 on 172.16.27.26 Sender: linux-media-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-media@vger.kernel.org Em Mon, 22 Jun 2009 11:02:58 -0500 "Karicheri, Muralidharan" escreveu: > Hi, > > > >> > > >> > -/** > >> > +/* > >> > * struct tvp514x_decoder - TVP5146/47 decoder object > >> > - * @v4l2_int_device: Slave handle > >> > - * @tvp514x_slave: Slave pointer which is used by @v4l2_int_device > >> > + * @sd: Subdevice Slave handle > >> > * @tvp514x_regs: copy of hw's regs with preset values. > >> > * @pdata: Board specific > >> > - * @client: I2C client data > >> > - * @id: Entry from I2C table > >> > * @ver: Chip version > >> > - * @state: TVP5146/47 decoder state - detected or not-detected > >> > + * @streaming: TVP5146/47 decoder streaming - enabled or disabled. > >> > * @pix: Current pixel format > >> > * @num_fmts: Number of formats > >> > * @fmt_list: Format list > >> > * @current_std: Current standard > >> > * @num_stds: Number of standards > >> > * @std_list: Standards list > >> > - * @route: input and output routing at chip level > >> > + * @input: Input routing at chip level > >> > + * @output: Output routing at chip level > >> > */ > >> > > >> > Please read Documentation/kernel-doc-nano-HOWTO.txt for the proper > >> > format. Basically, it should be like this example: > >> > > >> > /** > >> > * foobar() - short function description of foobar > >> > * @arg1: Describe the first argument to foobar. > >> > * @arg2: Describe the second argument to foobar. > >> > * One can provide multiple line descriptions > >> > * for arguments. > >> > * > >> > * A longer description, with more discussion of the function foobar() > >> > * that might be useful to those using or modifying it. Begins with > >> > * empty comment line, and may include additional embedded empty > >> > * comment lines. > >> > * > >> > * The longer description can have multiple paragraphs. > >> > **/ > >> > > But kernel-doc-nano-HOWTO.txt says it should be of the form > /** > * foobar() - short function description of foobar > * @arg1: Describe the first argument to foobar. > * @arg2: Describe the second argument to foobar. > * One can provide multiple line descriptions > * for arguments. > * > * A longer description, with more discussion of the function foobar() > * that might be useful to those using or modifying it. Begins with > * empty comment line, and may include additional embedded empty > * comment lines. > * > * The longer description can have multiple paragraphs. > */ > > Only one * followed by slash as */, not **/ as you have mentioned. > Please confirm so that I can send you a patch to correct this. You're right. It seems that I was using an older version of the doc, since it used to be like above, on the past versions of the doc: commit f40b45a2e45b0f02aeedfcfbb28d8e2d4b8b86b1 Author: Randy Dunlap Date: Wed Feb 11 13:04:31 2009 -0800 kernel-doc: preferred ending marker and examples Fix kernel-doc-nano-HOWTO.txt to use */ as the ending marker in kernel-doc examples and state that */ is the preferred ending marker. Signed-off-by: Randy Dunlap Reported-by: Robert Love Signed-off-by: Andrew Morton Signed-off-by: Linus Torvalds --- To unsubscribe from this list: send the line "unsubscribe linux-media" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html diff --git a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt index d73fbd2..026ec7d 100644 --- a/Documentation/kernel-doc-nano-HOWTO.txt +++ b/Documentation/kernel-doc-nano-HOWTO.txt @@ -43,7 +43,8 @@ Only comments so marked will be considered by the kernel-doc scripts, and any comment so marked must be in kernel-doc format. Do not use "/**" to be begin a comment block unless the comment block contains kernel-doc formatted comments. The closing comment marker for -kernel-doc comments can be either "*/" or "**/". +kernel-doc comments can be either "*/" or "**/", but "*/" is +preferred in the Linux kernel tree. Kernel-doc comments should be placed just before the function or data structure being described. @@ -63,7 +64,7 @@ Example kernel-doc function comment: * comment lines. * * The longer description can have multiple paragraphs. - **/ + */ The first line, with the short description, must be on a single line. @@ -85,7 +86,7 @@ Example kernel-doc data structure comment. * perhaps with more lines and words. * * Longer description of this structure. - **/ + */ The kernel-doc function comments describe each parameter to the function, in order, with the @name lines.