Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Date:   Thu, 5 Nov 2020 08:56:21 +0000
From:   Lee Jones <lee.jones@linaro.org>
To:     Jiri Slaby <jirislaby@kernel.org>
Cc:     linux-kernel@vger.kernel.org,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Subject: Re: [PATCH 08/36] tty: tty_ldisc: Fix some kernel-doc related
 misdemeanours
Message-ID: <20201105085621.GC4488@dell>
References: <20201104193549.4026187-1-lee.jones@linaro.org>
 <20201104193549.4026187-9-lee.jones@linaro.org>
 <8f07fa1e-d81f-fd43-9dfa-bfb9f9171619@kernel.org>
 <20201105085449.GB4488@dell>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <20201105085449.GB4488@dell>
Precedence: bulk

On Thu, 05 Nov 2020, Lee Jones wrote:

> On Thu, 05 Nov 2020, Jiri Slaby wrote:
> 
> > On 04. 11. 20, 20:35, Lee Jones wrote:
> > >   - Functions must follow directly on from their headers
> > >   - Demote non-conforming kernel-doc header
> > >   - Ensure notes have unique section names
> > >   - Provide missing description for 'reinit'
> > > 
> > > Fixes the following W=1 kernel build warning(s):
> > > 
> > >   drivers/tty/tty_ldisc.c:158: warning: cannot understand function prototype: 'int tty_ldisc_autoload = IS_BUILTIN(CONFIG_LDISC_AUTOLOAD); '
> > >   drivers/tty/tty_ldisc.c:199: warning: Function parameter or member 'ld' not described in 'tty_ldisc_put'
> > >   drivers/tty/tty_ldisc.c:260: warning: duplicate section name 'Note'
> > >   drivers/tty/tty_ldisc.c:717: warning: Function parameter or member 'reinit' not described in 'tty_ldisc_hangup'
> > > 
> > > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > > Cc: Jiri Slaby <jirislaby@kernel.org>
> > > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > > ---
> > >   drivers/tty/tty_ldisc.c | 10 +++++-----
> > >   1 file changed, 5 insertions(+), 5 deletions(-)
> > > 
> > > diff --git a/drivers/tty/tty_ldisc.c b/drivers/tty/tty_ldisc.c
> > > index fe37ec331289b..aced2bf6173be 100644
> > > --- a/drivers/tty/tty_ldisc.c
> > > +++ b/drivers/tty/tty_ldisc.c
> > > @@ -190,7 +189,7 @@ static struct tty_ldisc *tty_ldisc_get(struct tty_struct *tty, int disc)
> > >   	return ld;
> > >   }
> > > -/**
> > > +/*
> > >    *	tty_ldisc_put		-	release the ldisc
> > 
> > Having tty_ldisc_get in kernel-doc, while tty_ldisc_put not doesn't make
> > much sense. What's missing to tty_ldisc_put to conform to kernel-doc?
> 
> Where are they in kernel-doc?  I don't see any references.

Also:

 $ ./scripts/find-unused-docs.sh drivers/tty/
 The following files contain kerneldoc comments for exported functions that are not used in the formatted documentation
 drivers/tty/n_tracesink.c
 drivers/tty/tty_baudrate.c
 drivers/tty/serial/8250/8250_port.c
 drivers/tty/serdev/core.c
 drivers/tty/vt/keyboard.c
 drivers/tty/vt/selection.c
 drivers/tty/vt/consolemap.c
 drivers/tty/vt/vt.c
 drivers/tty/tty_jobctrl.c
 drivers/tty/tty_buffer.c
 drivers/tty/n_tty.c
 drivers/tty/hvc/hvc_console.c
 drivers/tty/tty_ioctl.c
 drivers/tty/sysrq.c
 drivers/tty/tty_ldisc.c                    <---------
 drivers/tty/tty_io.c
 drivers/tty/tty_port.c

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog