linux-kernel - Re: [PATCH v3 1/2] ARM: zynq: use restart

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20150319142226.GD23626@jcartwri.amer.corp.natinst.com>
Date:	Thu, 19 Mar 2015 09:22:26 -0500
From:	Josh Cartwright <joshc@...com>
To:	Michal Simek <michal.simek@...inx.com>
Cc:	S?ren Brinkmann <soren.brinkmann@...inx.com>,
	linux-kernel@...r.kernel.org, linux-arm-kernel@...ts.infradead.org
Subject: Re: [PATCH v3 1/2] ARM: zynq: use restart_handler mechanism for slcr
 reset

On Thu, Mar 19, 2015 at 03:01:13PM +0100, Michal Simek wrote:
> On 03/19/2015 02:33 PM, Josh Cartwright wrote:
[..]
> >  /**
> > - * zynq_slcr_system_reset - Reset the entire system.
> > + * zynq_slcr_system_restart - Restart the entire system.
> >   */
> > -void zynq_slcr_system_reset(void)
> > +static
> > +int zynq_slcr_system_restart(struct notifier_block *nb,
> > +			     unsigned long action, void *data)
> 
> This doesn't look right to me.
> 
> [linux]$ ./scripts/kernel-doc -man -v arch/arm/mach-zynq/slcr.c >/dev/null
> Info(arch/arm/mach-zynq/slcr.c:42): Scanning doc for zynq_slcr_write
> Info(arch/arm/mach-zynq/slcr.c:55): Scanning doc for zynq_slcr_read
> Info(arch/arm/mach-zynq/slcr.c:68): Scanning doc for zynq_slcr_unlock
> Info(arch/arm/mach-zynq/slcr.c:80): Scanning doc for zynq_slcr_get_device_id
> Info(arch/arm/mach-zynq/slcr.c:96): Scanning doc for zynq_slcr_system_restart
> Warning(arch/arm/mach-zynq/slcr.c:101): No description found for parameter 'nb'
> Warning(arch/arm/mach-zynq/slcr.c:101): No description found for parameter 'action'
> Warning(arch/arm/mach-zynq/slcr.c:101): No description found for parameter 'data'
> Warning(arch/arm/mach-zynq/slcr.c:101): No description found for return value of 'zynq_slcr_system_restart'

*Sigh*.  I guess now is as good as ever to learn how to write kerneldoc.

I can't help but feel this effort really isn't worth it.  I'll do it,
obviously, because I want this patch to go in, but I really don't
understand at all what value is being provided here.

Are you advocating for _every_ function in the kernel to have an
associated kerneldoc annotation?  Even for small/self-evident/internal
functions?

In my opinion, kerneldoc annotations make sense for those functions
which:

  1.) Are widely used (think synchronization primitives, device core, etc.)
  2.) Have non-obvious semantics, or:
  3.) Have caller-mandated requirements that aren't clear otherwise
      (locks to be acquired, lifecycle management requirements, state to
       be maintained, etc.)

Beyond that, it's just review churn and fighting the inevitable
code-and-documentation-out-of-sync problem.

  Josh
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@...r.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/