From: <Tim.Bird@sony.com>
To: <jani.nikula@linux.intel.com>, <changbin.du@gmail.com>, <corbet@lwn.net>
Cc: <linux-pci@vger.kernel.org>, <linux-doc@vger.kernel.org>,
<linux-kernel@vger.kernel.org>, <linux-mm@kvack.org>,
<linux-crypto@vger.kernel.org>, <linux-kselftest@vger.kernel.org>,
<linux-wireless@vger.kernel.org>, <linux-fpga@vger.kernel.org>,
<linux-usb@vger.kernel.org>, <dri-devel@lists.freedesktop.org>,
<intel-gfx@lists.freedesktop.org>, <changbin.du@gmail.com>
Subject: RE: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Date: Mon, 14 Oct 2019 20:48:48 +0000 [thread overview]
Message-ID: <ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com> (raw)
In-Reply-To: <875zkrd7nq.fsf@intel.com>
> -----Original Message-----
> From: Jani Nikula on October 13, 2019 11:00 PM
> On Sun, 13 Oct 2019, Changbin Du <changbin.du@gmail.com> wrote:
> > The 'functions' directive is not only for functions, but also works for
> > structs/unions. So the name is misleading. This patch renames it to
> > 'specific', so now we have export/internal/specific directives to limit
> > the functions/types to be included in documentation. Meanwhile we
> improved
> > the warning message.
>
> Agreed on "functions" being less than perfect. It directly exposes the
> idiosyncrasies of scripts/kernel-doc. I'm not sure "specific" is any
> better, though.
I strongly agree with this. 'specific' IMHO, has no semantic value and
I'd rather just leave the only-sometimes-wrong 'functions' than convert
to something that obscures the meaning always.
>
> Perhaps "symbols" would be more self-explanatory. Or, actually make
> "functions" only work on functions, and add a separate keyword for other
> stuff. *shrug*
My preference would be to use 'symbols'. I tried to come up with something
but 'symbols' is better than anything I came up with.
>
> Seems like the patch is way too big. I'd probably add "symbols" (or
> whatever) as a synonym for "functions" for starters, and convert
> documents piecemeal, and finally drop the old one.
>
> The scripts/kernel-doc change should be a patch of its own.
Agreed on these two points as well.
Just adding my 2 cents.
-- Tim
WARNING: multiple messages have this Message-ID (diff)
From: <Tim.Bird@sony.com>
To: jani.nikula@linux.intel.com, changbin.du@gmail.com, corbet@lwn.net
Cc: linux-pci@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, linux-mm@kvack.org,
linux-crypto@vger.kernel.org, linux-kselftest@vger.kernel.org,
linux-wireless@vger.kernel.org, linux-fpga@vger.kernel.org,
linux-usb@vger.kernel.org, dri-devel@lists.freedesktop.org,
intel-gfx@lists.freedesktop.org
Subject: RE: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Date: Mon, 14 Oct 2019 20:48:48 +0000 [thread overview]
Message-ID: <ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com> (raw)
In-Reply-To: <875zkrd7nq.fsf@intel.com>
> -----Original Message-----
> From: Jani Nikula on October 13, 2019 11:00 PM
> On Sun, 13 Oct 2019, Changbin Du <changbin.du@gmail.com> wrote:
> > The 'functions' directive is not only for functions, but also works for
> > structs/unions. So the name is misleading. This patch renames it to
> > 'specific', so now we have export/internal/specific directives to limit
> > the functions/types to be included in documentation. Meanwhile we
> improved
> > the warning message.
>
> Agreed on "functions" being less than perfect. It directly exposes the
> idiosyncrasies of scripts/kernel-doc. I'm not sure "specific" is any
> better, though.
I strongly agree with this. 'specific' IMHO, has no semantic value and
I'd rather just leave the only-sometimes-wrong 'functions' than convert
to something that obscures the meaning always.
>
> Perhaps "symbols" would be more self-explanatory. Or, actually make
> "functions" only work on functions, and add a separate keyword for other
> stuff. *shrug*
My preference would be to use 'symbols'. I tried to come up with something
but 'symbols' is better than anything I came up with.
>
> Seems like the patch is way too big. I'd probably add "symbols" (or
> whatever) as a synonym for "functions" for starters, and convert
> documents piecemeal, and finally drop the old one.
>
> The scripts/kernel-doc change should be a patch of its own.
Agreed on these two points as well.
Just adding my 2 cents.
-- Tim
WARNING: multiple messages have this Message-ID (diff)
From: <Tim.Bird-7U/KSKJipcs@public.gmane.org>
To: jani.nikula-VuQAYsv1563Yd54FQh9/CA@public.gmane.org,
corbet-T1hC0tSOHrs@public.gmane.org
Cc: linux-pci-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-doc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-kernel-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-mm-Bw31MaZKKs3YtjvyW6yDsg@public.gmane.org,
linux-crypto-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-kselftest-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-wireless-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-fpga-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
linux-usb-u79uwXL29TY76Z2rM5mHXA@public.gmane.org,
dri-devel-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org,
intel-gfx-PD4FTy7X32lNgt0PjOBp9y5qC8QIuHrW@public.gmane.org,
changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
Subject: RE: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Date: Mon, 14 Oct 2019 20:48:48 +0000 [thread overview]
Message-ID: <ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com> (raw)
In-Reply-To: <875zkrd7nq.fsf-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org>
> -----Original Message-----
> From: Jani Nikula on October 13, 2019 11:00 PM
> On Sun, 13 Oct 2019, Changbin Du <changbin.du-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> > The 'functions' directive is not only for functions, but also works for
> > structs/unions. So the name is misleading. This patch renames it to
> > 'specific', so now we have export/internal/specific directives to limit
> > the functions/types to be included in documentation. Meanwhile we
> improved
> > the warning message.
>
> Agreed on "functions" being less than perfect. It directly exposes the
> idiosyncrasies of scripts/kernel-doc. I'm not sure "specific" is any
> better, though.
I strongly agree with this. 'specific' IMHO, has no semantic value and
I'd rather just leave the only-sometimes-wrong 'functions' than convert
to something that obscures the meaning always.
>
> Perhaps "symbols" would be more self-explanatory. Or, actually make
> "functions" only work on functions, and add a separate keyword for other
> stuff. *shrug*
My preference would be to use 'symbols'. I tried to come up with something
but 'symbols' is better than anything I came up with.
>
> Seems like the patch is way too big. I'd probably add "symbols" (or
> whatever) as a synonym for "functions" for starters, and convert
> documents piecemeal, and finally drop the old one.
>
> The scripts/kernel-doc change should be a patch of its own.
Agreed on these two points as well.
Just adding my 2 cents.
-- Tim
next prev parent reply other threads:[~2019-10-14 20:49 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-10-13 5:53 [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific' Changbin Du
2019-10-13 19:29 ` kbuild test robot
2019-10-13 19:29 ` kbuild test robot
2019-10-13 19:29 ` kbuild test robot
2019-10-13 19:29 ` kbuild test robot
2019-10-14 8:59 ` Jani Nikula
2019-10-14 8:59 ` Jani Nikula
2019-10-14 8:59 ` Jani Nikula
2019-10-14 20:48 ` Tim.Bird [this message]
2019-10-14 20:48 ` Tim.Bird-7U/KSKJipcs
2019-10-14 20:48 ` Tim.Bird
2019-10-15 3:15 ` Matthew Wilcox
2019-10-15 9:25 ` Thomas Zimmermann
2019-10-15 9:25 ` Thomas Zimmermann
2019-10-15 11:54 ` Matthew Wilcox
2019-10-15 12:08 ` Thomas Zimmermann
2019-10-15 12:08 ` Thomas Zimmermann
2019-10-15 13:19 ` Jani Nikula
2019-10-15 13:19 ` Jani Nikula
2019-10-16 0:03 ` Changbin Du
2019-10-16 0:48 ` Matthew Wilcox
2019-10-16 0:48 ` Matthew Wilcox
2019-10-14 20:26 ` ✗ Fi.CI.CHECKPATCH: warning for " Patchwork
2019-10-14 20:46 ` ✓ Fi.CI.BAT: success " Patchwork
2019-10-15 8:40 ` ✓ Fi.CI.IGT: " Patchwork
2019-10-15 18:27 ` [PATCH] " Jonathan Corbet
2019-10-16 0:10 ` Changbin Du
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=ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com \
--to=tim.bird@sony.com \
--cc=changbin.du@gmail.com \
--cc=corbet@lwn.net \
--cc=dri-devel@lists.freedesktop.org \
--cc=intel-gfx@lists.freedesktop.org \
--cc=jani.nikula@linux.intel.com \
--cc=linux-crypto@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-fpga@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=linux-pci@vger.kernel.org \
--cc=linux-usb@vger.kernel.org \
--cc=linux-wireless@vger.kernel.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.