From: Thomas Zimmermann <tzimmermann@suse.de> To: Tim.Bird@sony.com, jani.nikula@linux.intel.com, changbin.du@gmail.com, corbet@lwn.net Cc: linux-doc@vger.kernel.org, linux-pci@vger.kernel.org, linux-fpga@vger.kernel.org, linux-usb@vger.kernel.org, linux-wireless@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-mm@kvack.org, linux-crypto@vger.kernel.org, linux-kselftest@vger.kernel.org, intel-gfx@lists.freedesktop.org Subject: Re: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific' Date: Tue, 15 Oct 2019 11:25:53 +0200 [thread overview] Message-ID: <7e7557b5-469f-3e63-6254-53dab2d7234a@suse.de> (raw) In-Reply-To: <ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com> [-- Attachment #1.1: Type: text/plain, Size: 2084 bytes --] Hi Am 14.10.19 um 22:48 schrieb Tim.Bird@sony.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. Maybe 'interfaces' or 'artifacts'. The term 'symbols' is just as imprecise as 'functions'. Best regards Thomas >> >> 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 > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel > -- Thomas Zimmermann Graphics Driver Developer SUSE Software Solutions Germany GmbH Maxfeldstr. 5, 90409 Nürnberg, Germany (HRB 36809, AG Nürnberg) Geschäftsführer: Felix Imendörffer [-- Attachment #2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 488 bytes --]
WARNING: multiple messages have this Message-ID (diff)
From: Thomas Zimmermann <tzimmermann@suse.de> To: Tim.Bird@sony.com, jani.nikula@linux.intel.com, changbin.du@gmail.com, corbet@lwn.net Cc: linux-doc@vger.kernel.org, linux-pci@vger.kernel.org, linux-fpga@vger.kernel.org, linux-usb@vger.kernel.org, linux-wireless@vger.kernel.org, linux-kernel@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-mm@kvack.org, linux-crypto@vger.kernel.org, linux-kselftest@vger.kernel.org, intel-gfx@lists.freedesktop.org Subject: Re: [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific' Date: Tue, 15 Oct 2019 11:25:53 +0200 [thread overview] Message-ID: <7e7557b5-469f-3e63-6254-53dab2d7234a@suse.de> (raw) In-Reply-To: <ECADFF3FD767C149AD96A924E7EA6EAF977CAF09@USCULXMSG01.am.sony.com> [-- Attachment #1.1.1: Type: text/plain, Size: 2084 bytes --] Hi Am 14.10.19 um 22:48 schrieb Tim.Bird@sony.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. Maybe 'interfaces' or 'artifacts'. The term 'symbols' is just as imprecise as 'functions'. Best regards Thomas >> >> 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 > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel > -- Thomas Zimmermann Graphics Driver Developer SUSE Software Solutions Germany GmbH Maxfeldstr. 5, 90409 Nürnberg, Germany (HRB 36809, AG Nürnberg) Geschäftsführer: Felix Imendörffer [-- Attachment #1.2: OpenPGP digital signature --] [-- Type: application/pgp-signature, Size: 488 bytes --] [-- Attachment #2: Type: text/plain, Size: 159 bytes --] _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
next prev parent reply other threads:[~2019-10-15 9:26 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 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 [this message] 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=7e7557b5-469f-3e63-6254-53dab2d7234a@suse.de \ --to=tzimmermann@suse.de \ --cc=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: linkBe 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.