Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Tue, Oct 15, 2019 at 04:54:39AM -0700, Matthew Wilcox wrote: > On Tue, Oct 15, 2019 at 11:25:53AM +0200, Thomas Zimmermann wrote: > > > 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'. > > I suggested 'identifier' because that's the term used in the C spec (6.2.1): > > : An identifier can denote an object; a function; a tag or a member > : of a structure, union, or enumeration; a typedef name; a label name; > : a macro name; or a macro parameter. > I also prefer this one now. I was looking for something like this. My original idea is 'prototype', but that is only for function. > We don't allow documenting all those things separately, but it does cover > all the things we do allow to be individually documented. -- Cheers, Changbin Du ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Tue, Oct 15, 2019 at 12:27:26PM -0600, Jonathan Corbet wrote: > On Sun, 13 Oct 2019 13:53:59 +0800 > Changbin Du 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. > > I agree with the others that "specific" doesn't really make things > better. "Interfaces" maybe; otherwise we could go for something like > "filter" or "select". > Jonathan, How about 'identifier' suggested by Matthew as it is mentioned in Then C spec? > Paint mine green :) > > Whatever we end up with, I think it should be added as a synonym for > "functions". Then the various selectors that are actually pulling out > docs for functions could be changed at leisure - or not at all. I'd > rather not see a big patch changing everything at once. > Sure, I'll make 'functions' deprecated and as an alias to our new directive name. > Thanks, > > jon -- Cheers, Changbin Du ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Wed, Oct 16, 2019 at 08:03:24AM +0800, Changbin Du wrote: > On Tue, Oct 15, 2019 at 04:54:39AM -0700, Matthew Wilcox wrote: > > On Tue, Oct 15, 2019 at 11:25:53AM +0200, Thomas Zimmermann wrote: > > > > 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'. > > > > I suggested 'identifier' because that's the term used in the C spec (6.2.1): > > > > : An identifier can denote an object; a function; a tag or a member > > : of a structure, union, or enumeration; a typedef name; a label name; > > : a macro name; or a macro parameter. > > I also prefer this one now. I was looking for something like this. My original > idea is 'prototype', but that is only for function. We could also go with 'declaration' or 'definition'. But I prefer 'identifier'. ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Sun, 13 Oct 2019 13:53:59 +0800 Changbin Du 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. I agree with the others that "specific" doesn't really make things better. "Interfaces" maybe; otherwise we could go for something like "filter" or "select". Paint mine green :) Whatever we end up with, I think it should be added as a synonym for "functions". Then the various selectors that are actually pulling out docs for functions could be changed at leisure - or not at all. I'd rather not see a big patch changing everything at once. Thanks, jon ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Tue, 15 Oct 2019, Matthew Wilcox wrote: > On Tue, Oct 15, 2019 at 11:25:53AM +0200, Thomas Zimmermann wrote: >> > 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'. > > I suggested 'identifier' because that's the term used in the C spec (6.2.1): > > : An identifier can denote an object; a function; a tag or a member > : of a structure, union, or enumeration; a typedef name; a label name; > : a macro name; or a macro parameter. > > We don't allow documenting all those things separately, but it does cover > all the things we do allow to be individually documented. Agreed. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Hi Am 15.10.19 um 13:54 schrieb Matthew Wilcox: > On Tue, Oct 15, 2019 at 11:25:53AM +0200, Thomas Zimmermann wrote: >>> 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'. > > I suggested 'identifier' because that's the term used in the C spec (6.2.1): > > : An identifier can denote an object; a function; a tag or a member > : of a structure, union, or enumeration; a typedef name; a label name; > : a macro name; or a macro parameter. > > We don't allow documenting all those things separately, but it does cover > all the things we do allow to be individually documented. > Yeah, makes sense. Best regards Thomas -- 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 signature.asc Description: OpenPGP digital signature ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Tue, Oct 15, 2019 at 11:25:53AM +0200, Thomas Zimmermann wrote: > > 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'. I suggested 'identifier' because that's the term used in the C spec (6.2.1): : An identifier can denote an object; a function; a tag or a member : of a structure, union, or enumeration; a typedef name; a label name; : a macro name; or a macro parameter. We don't allow documenting all those things separately, but it does cover all the things we do allow to be individually documented. ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Hi Am 14.10.19 um 22:48 schrieb tim.b...@sony.com: > > >> -Original Message- >> From: Jani Nikula on October 13, 2019 11:00 PM >> On Sun, 13 Oct 2019, Changbin Du 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-de...@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 signature.asc Description: OpenPGP digital signature ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Mon, Oct 14, 2019 at 08:48:48PM +, tim.b...@sony.com wrote: > > > > -Original Message- > > From: Jani Nikula on October 13, 2019 11:00 PM > > On Sun, 13 Oct 2019, Changbin Du 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. structures aren't symbols though ... How about 'identifier'? ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
> -Original Message- > From: Jani Nikula on October 13, 2019 11:00 PM > On Sun, 13 Oct 2019, Changbin Du 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 ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
On Sun, 13 Oct 2019, Changbin Du 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. Perhaps "symbols" would be more self-explanatory. Or, actually make "functions" only work on functions, and add a separate keyword for other stuff. *shrug* 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. BR, Jani. -- Jani Nikula, Intel Open Source Graphics Center ___ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
Re: [Intel-gfx] [PATCH] kernel-doc: rename the kernel-doc directive 'functions' to 'specific'
Hi Changbin, Thank you for the patch! Perhaps something to improve: [auto build test WARNING on linus/master] [cannot apply to v5.4-rc2 next-20191010] [if your patch is applied to the wrong git tree, please drop us a note to help improve the system. BTW, we also suggest to use '--base' option to specify the base tree in git format-patch, please see https://stackoverflow.com/a/37406982] url: https://github.com/0day-ci/linux/commits/Changbin-Du/kernel-doc-rename-the-kernel-doc-directive-functions-to-specific/20191014-013215 reproduce: make htmldocs If you fix the issue, kindly add following tag Reported-by: kbuild test robot All warnings (new ones prefixed by >>): Warning: The Sphinx 'sphinx_rtd_theme' HTML theme was not found. Make sure you have the theme installed to produce pretty HTML output. Falling back to the default theme. WARNING: dot(1) not found, for better output quality install graphviz from http://www.graphviz.org WARNING: convert(1) not found, for SVG to PDF conversion install ImageMagick (https://www.imagemagick.org) Error: Cannot open file drivers/dma-buf/reservation.c Error: Cannot open file drivers/dma-buf/reservation.c Error: Cannot open file drivers/dma-buf/reservation.c Error: Cannot open file include/linux/reservation.h Error: Cannot open file include/linux/reservation.h >> include/linux/regulator/machine.h:196: warning: struct member 'max_uV_step' >> not described in 'regulation_constraints' >> include/linux/regulator/driver.h:223: warning: struct member 'resume' not >> described in 'regulator_ops' >> include/linux/i2c.h:337: warning: struct member 'init_irq' not described in >> 'i2c_client' drivers/gpio/gpiolib-of.c:92: warning: Excess function parameter 'dev' description in 'of_gpio_need_valid_mask' >> include/linux/spi/spi.h:190: warning: struct member 'driver_override' not >> described in 'spi_device' mm/util.c:1: warning: 'get_user_pages_fast' not found >> mm/slab.c:4215: warning: function parameter 'objp' not described in '__ksize' drivers/usb/typec/bus.c:1: warning: 'typec_altmode_register_driver' not found drivers/usb/typec/bus.c:1: warning: 'typec_altmode_unregister_driver' not found drivers/usb/typec/class.c:1: warning: 'typec_altmode_unregister_notifier' not found drivers/usb/typec/class.c:1: warning: 'typec_altmode_register_notifier' not found >> include/linux/w1.h:277: warning: struct member 'of_match_table' not >> described in 'w1_family' drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c:335: warning: Excess function parameter 'dev' description in 'amdgpu_gem_prime_export' drivers/gpu/drm/amd/amdgpu/amdgpu_dma_buf.c:336: warning: Excess function parameter 'dev' description in 'amdgpu_gem_prime_export' >> drivers/gpu/drm/amd/amdgpu/amdgpu_mn.c:142: warning: function parameter >> 'blockable' not described in 'amdgpu_mn_read_lock' drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:347: warning: cannot understand function prototype: 'struct amdgpu_vm_pt_cursor ' drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:348: warning: cannot understand function prototype: 'struct amdgpu_vm_pt_cursor ' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:494: warning: function parameter >> 'start' not described in 'amdgpu_vm_pt_first_dfs' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter >> 'adev' not described in 'for_each_amdgpu_vm_pt_dfs_safe' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter 'vm' >> not described in 'for_each_amdgpu_vm_pt_dfs_safe' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter >> 'start' not described in 'for_each_amdgpu_vm_pt_dfs_safe' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter >> 'cursor' not described in 'for_each_amdgpu_vm_pt_dfs_safe' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:546: warning: function parameter >> 'entry' not described in 'for_each_amdgpu_vm_pt_dfs_safe' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:821: warning: function parameter >> 'level' not described in 'amdgpu_vm_bo_param' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'params' not described in 'amdgpu_vm_update_flags' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'bo' not described in 'amdgpu_vm_update_flags' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'level' not described in 'amdgpu_vm_update_flags' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'pe' not described in 'amdgpu_vm_update_flags' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'addr' not described in 'amdgpu_vm_update_flags' >> drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c:1283: warning: function parameter >> 'count' not described in 'amdgpu_vm_update_flags' vim +1207 drivers/gpu/drm/i915/i915_drv.h eec688e1420da5 Robert Bragg 2016-11-07 1069 16d98b31f80775 Robert Bragg 2016-12-07 1070
