All of lore.kernel.org
 help / color / mirror / Atom feed
From: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
To: Laurent Pinchart
	<laurent.pinchart-ryLnwIuWjnjg/C1BVhZhaw@public.gmane.org>
Cc: linux-media-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
	niklas.soderlund-1zkq55x86MTxsAP9Fp7wbw@public.gmane.org,
	robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org,
	hverkuil-qWit8jRvyhVmR6Xm/wNWPw@public.gmane.org,
	devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
Subject: Re: [PATCH v5 1/5] v4l: fwnode: Move KernelDoc documentation to the header
Date: Tue, 29 Aug 2017 16:20:10 +0300	[thread overview]
Message-ID: <20170829132010.nfofeofidvpipw4h@paasikivi.fi.intel.com> (raw)
In-Reply-To: <2676284.rKR023OhTM@avalon>

Hi Laurent,

On Tue, Aug 29, 2017 at 04:15:22PM +0300, Laurent Pinchart wrote:
> Hi Sakari,
> 
> Thank you for the patch.
> 
> On Tuesday, 29 August 2017 14:03:09 EEST Sakari Ailus wrote:
> > In V4L2 the practice is to have the KernelDoc documentation in the header
> > and not in .c source code files. This consequientally makes the V4L2
> > fwnode function documentation part of the Media documentation build.
> > 
> > Also correct the link related function and argument naming in
> > documentation.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> 
> I prefer documenting functions in the C file. Documentation in header files 
> will get out-of-sync with the implementation much more easily.

The fact is that there's very little KernelDoc documentation left in the .c
files in V4L2. This actually appears to be the only exception. And it seems
to have been in the Sphinx build; I missed that earlier, so that part of
the commit message doesn't apply.

-- 
Sakari Ailus
sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org
--
To unsubscribe from this list: send the line "unsubscribe devicetree" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

WARNING: multiple messages have this Message-ID (diff)
From: Sakari Ailus <sakari.ailus@linux.intel.com>
To: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Cc: linux-media@vger.kernel.org, niklas.soderlund@ragnatech.se,
	robh@kernel.org, hverkuil@xs4all.nl, devicetree@vger.kernel.org
Subject: Re: [PATCH v5 1/5] v4l: fwnode: Move KernelDoc documentation to the header
Date: Tue, 29 Aug 2017 16:20:10 +0300	[thread overview]
Message-ID: <20170829132010.nfofeofidvpipw4h@paasikivi.fi.intel.com> (raw)
In-Reply-To: <2676284.rKR023OhTM@avalon>

Hi Laurent,

On Tue, Aug 29, 2017 at 04:15:22PM +0300, Laurent Pinchart wrote:
> Hi Sakari,
> 
> Thank you for the patch.
> 
> On Tuesday, 29 August 2017 14:03:09 EEST Sakari Ailus wrote:
> > In V4L2 the practice is to have the KernelDoc documentation in the header
> > and not in .c source code files. This consequientally makes the V4L2
> > fwnode function documentation part of the Media documentation build.
> > 
> > Also correct the link related function and argument naming in
> > documentation.
> > 
> > Signed-off-by: Sakari Ailus <sakari.ailus@linux.intel.com>
> 
> I prefer documenting functions in the C file. Documentation in header files 
> will get out-of-sync with the implementation much more easily.

The fact is that there's very little KernelDoc documentation left in the .c
files in V4L2. This actually appears to be the only exception. And it seems
to have been in the Sphinx build; I missed that earlier, so that part of
the commit message doesn't apply.

-- 
Sakari Ailus
sakari.ailus@linux.intel.com

  reply	other threads:[~2017-08-29 13:20 UTC|newest]

Thread overview: 27+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2017-08-29 11:03 [PATCH v5 0/5] Unified fwnode endpoint parser Sakari Ailus
2017-08-29 11:03 ` Sakari Ailus
     [not found] ` <20170829110313.19538-1-sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
2017-08-29 11:03   ` [PATCH v5 1/5] v4l: fwnode: Move KernelDoc documentation to the header Sakari Ailus
2017-08-29 11:03     ` Sakari Ailus
     [not found]     ` <20170829110313.19538-2-sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
2017-08-29 12:50       ` Niklas Söderlund
2017-08-29 12:50         ` Niklas Söderlund
2017-08-29 13:15     ` Laurent Pinchart
2017-08-29 13:20       ` Sakari Ailus [this message]
2017-08-29 13:20         ` Sakari Ailus
2017-08-29 13:22         ` Sakari Ailus
2017-08-29 11:03   ` [PATCH v5 2/5] v4l: async: Add V4L2 async documentation to the documentation build Sakari Ailus
2017-08-29 11:03     ` Sakari Ailus
2017-08-29 12:52     ` Niklas Söderlund
2017-08-29 11:03   ` [PATCH v5 4/5] v4l: fwnode: Support generic parsing of graph endpoints in a device Sakari Ailus
2017-08-29 11:03     ` Sakari Ailus
     [not found]     ` <20170829110313.19538-5-sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
2017-08-29 14:02       ` Laurent Pinchart
2017-08-29 14:02         ` Laurent Pinchart
2017-08-29 14:31         ` Sakari Ailus
2017-08-29 14:31           ` Sakari Ailus
     [not found]           ` <20170829143121.6sjdx3lgcoxm6mva-S+BSfZ9RZZmRSg0ZkenSGLdO1Tsj/99ntUK59QYPAWc@public.gmane.org>
2017-09-01  8:55             ` Laurent Pinchart
2017-09-01  8:55               ` Laurent Pinchart
2017-09-01  9:04               ` Sakari Ailus
2017-08-29 11:03 ` [PATCH v5 3/5] docs-rst: v4l: Include Qualcomm CAMSS in documentation build Sakari Ailus
     [not found]   ` <20170829110313.19538-4-sakari.ailus-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
2017-08-29 13:32     ` Laurent Pinchart
2017-08-29 13:32       ` Laurent Pinchart
2017-08-29 11:03 ` [PATCH v5 5/5] v4l: fwnode: Support generic parsing of graph endpoints in a single port Sakari Ailus
2017-08-29 12:57   ` Niklas Söderlund

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20170829132010.nfofeofidvpipw4h@paasikivi.fi.intel.com \
    --to=sakari.ailus-vuqaysv1563yd54fqh9/ca@public.gmane.org \
    --cc=devicetree-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
    --cc=hverkuil-qWit8jRvyhVmR6Xm/wNWPw@public.gmane.org \
    --cc=laurent.pinchart-ryLnwIuWjnjg/C1BVhZhaw@public.gmane.org \
    --cc=linux-media-u79uwXL29TY76Z2rM5mHXA@public.gmane.org \
    --cc=niklas.soderlund-1zkq55x86MTxsAP9Fp7wbw@public.gmane.org \
    --cc=robh-DgEjT+Ai2ygdnm+yROfE0A@public.gmane.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body. 
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.