[PATCH] staging: fbtft: add docs for fbtft_write_spi()

[PATCH] staging: fbtft: add docs for fbtft_write_spi()

[Zachary Mayhew]

Subject: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

This patch adds documentation for fbtft_write_spi() to make its
calling context clear and explain what it does.

Signed-off-by: Zachary Mayhew <zacklukem.kernel@gmail.com>
---
 drivers/staging/fbtft/fbtft-io.c | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/drivers/staging/fbtft/fbtft-io.c b/drivers/staging/fbtft/fbtft-io.c
index de1904a443c2..985d7cf8c774 100644
--- a/drivers/staging/fbtft/fbtft-io.c
+++ b/drivers/staging/fbtft/fbtft-io.c
@@ -5,6 +5,19 @@
 #include <linux/spi/spi.h>
 #include "fbtft.h"
 
+/**
+ * fbtft_write_spi() - write data to current spi
+ * @par: Driver data including driver &struct spi_device
+ * @buf: Buffer to write to spi
+ * @len: Length of the buffer
+ * Context: can sleep
+ *
+ * Builds an &struct spi_transfer and &struct spi_message object based on the
+ * given @buf and @len.  These are then used in a call to spi_sync() which will
+ * write to the spi.
+ *
+ * Return: zero on success or else a negative error code
+ */
 int fbtft_write_spi(struct fbtft_par *par, void *buf, size_t len)
 {
 	struct spi_transfer t = {
-- 
2.33.0

Re: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

[Greg KH]

On Mon, Sep 20, 2021 at 08:26:03AM -0700, Zachary Mayhew wrote:
> Subject: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

Odd, this shouldn't be in the body of the email :(

> 
> This patch adds documentation for fbtft_write_spi() to make its
> calling context clear and explain what it does.
> 
> Signed-off-by: Zachary Mayhew <zacklukem.kernel@gmail.com>
> ---
>  drivers/staging/fbtft/fbtft-io.c | 13 +++++++++++++
>  1 file changed, 13 insertions(+)
> 
> diff --git a/drivers/staging/fbtft/fbtft-io.c b/drivers/staging/fbtft/fbtft-io.c
> index de1904a443c2..985d7cf8c774 100644
> --- a/drivers/staging/fbtft/fbtft-io.c
> +++ b/drivers/staging/fbtft/fbtft-io.c
> @@ -5,6 +5,19 @@
>  #include <linux/spi/spi.h>
>  #include "fbtft.h"
>  
> +/**
> + * fbtft_write_spi() - write data to current spi
> + * @par: Driver data including driver &struct spi_device
> + * @buf: Buffer to write to spi
> + * @len: Length of the buffer
> + * Context: can sleep
> + *
> + * Builds an &struct spi_transfer and &struct spi_message object based on the
> + * given @buf and @len.  These are then used in a call to spi_sync() which will
> + * write to the spi.
> + *
> + * Return: zero on success or else a negative error code
> + */
>  int fbtft_write_spi(struct fbtft_par *par, void *buf, size_t len)
>  {
>  	struct spi_transfer t = {
> -- 
> 2.33.0
> 
> 

Is this file being imported into the kernel doc tools?  If so, great, if
not, this isn't going to help out all that much, right?

thanks,

greg k-h

Re: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

[Zachary Mayhew]

On Mon, Sep 20, 2021 at 05:38:30PM +0200, Greg KH wrote:
> On Mon, Sep 20, 2021 at 08:26:03AM -0700, Zachary Mayhew wrote:
> > Subject: [PATCH] staging: fbtft: add docs for fbtft_write_spi()
> 
> Odd, this shouldn't be in the body of the email :(
> 
> > 
> > This patch adds documentation for fbtft_write_spi() to make its
> > calling context clear and explain what it does.
> > 
> > Signed-off-by: Zachary Mayhew <zacklukem.kernel@gmail.com>
> > ---
> >  drivers/staging/fbtft/fbtft-io.c | 13 +++++++++++++
> >  1 file changed, 13 insertions(+)
> > 
> > diff --git a/drivers/staging/fbtft/fbtft-io.c b/drivers/staging/fbtft/fbtft-io.c
> > index de1904a443c2..985d7cf8c774 100644
> > --- a/drivers/staging/fbtft/fbtft-io.c
> > +++ b/drivers/staging/fbtft/fbtft-io.c
> > @@ -5,6 +5,19 @@
> >  #include <linux/spi/spi.h>
> >  #include "fbtft.h"
> >  
> > +/**
> > + * fbtft_write_spi() - write data to current spi
> > + * @par: Driver data including driver &struct spi_device
> > + * @buf: Buffer to write to spi
> > + * @len: Length of the buffer
> > + * Context: can sleep
> > + *
> > + * Builds an &struct spi_transfer and &struct spi_message object based on the
> > + * given @buf and @len.  These are then used in a call to spi_sync() which will
> > + * write to the spi.
> > + *
> > + * Return: zero on success or else a negative error code
> > + */
> >  int fbtft_write_spi(struct fbtft_par *par, void *buf, size_t len)
> >  {
> >  	struct spi_transfer t = {
> > -- 
> > 2.33.0
> > 
> > 
> 
> Is this file being imported into the kernel doc tools?  If so, great, if
> not, this isn't going to help out all that much, right?

It doesn't appear to be imported at this time, as such it may not be
necessary.

> 
> thanks,
> 
> greg k-h

Thanks,
-Zachary Mayhew

Re: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

[Greg KH]

On Mon, Sep 20, 2021 at 09:07:13AM -0700, Zachary Mayhew wrote:
> On Mon, Sep 20, 2021 at 05:38:30PM +0200, Greg KH wrote:
> > On Mon, Sep 20, 2021 at 08:26:03AM -0700, Zachary Mayhew wrote:
> > > Subject: [PATCH] staging: fbtft: add docs for fbtft_write_spi()
> > 
> > Odd, this shouldn't be in the body of the email :(
> > 
> > > 
> > > This patch adds documentation for fbtft_write_spi() to make its
> > > calling context clear and explain what it does.
> > > 
> > > Signed-off-by: Zachary Mayhew <zacklukem.kernel@gmail.com>
> > > ---
> > >  drivers/staging/fbtft/fbtft-io.c | 13 +++++++++++++
> > >  1 file changed, 13 insertions(+)
> > > 
> > > diff --git a/drivers/staging/fbtft/fbtft-io.c b/drivers/staging/fbtft/fbtft-io.c
> > > index de1904a443c2..985d7cf8c774 100644
> > > --- a/drivers/staging/fbtft/fbtft-io.c
> > > +++ b/drivers/staging/fbtft/fbtft-io.c
> > > @@ -5,6 +5,19 @@
> > >  #include <linux/spi/spi.h>
> > >  #include "fbtft.h"
> > >  
> > > +/**
> > > + * fbtft_write_spi() - write data to current spi
> > > + * @par: Driver data including driver &struct spi_device
> > > + * @buf: Buffer to write to spi
> > > + * @len: Length of the buffer
> > > + * Context: can sleep
> > > + *
> > > + * Builds an &struct spi_transfer and &struct spi_message object based on the
> > > + * given @buf and @len.  These are then used in a call to spi_sync() which will
> > > + * write to the spi.
> > > + *
> > > + * Return: zero on success or else a negative error code
> > > + */
> > >  int fbtft_write_spi(struct fbtft_par *par, void *buf, size_t len)
> > >  {
> > >  	struct spi_transfer t = {
> > > -- 
> > > 2.33.0
> > > 
> > > 
> > 
> > Is this file being imported into the kernel doc tools?  If so, great, if
> > not, this isn't going to help out all that much, right?
> 
> It doesn't appear to be imported at this time, as such it may not be
> necessary.

So is this change needed?

thanks,

greg k-h

Re: [PATCH] staging: fbtft: add docs for fbtft_write_spi()

[Zachary Mayhew]

On Mon, Sep 20, 2021 at 06:18:58PM +0200, Greg KH wrote:
> On Mon, Sep 20, 2021 at 09:07:13AM -0700, Zachary Mayhew wrote:
> > On Mon, Sep 20, 2021 at 05:38:30PM +0200, Greg KH wrote:
> > > On Mon, Sep 20, 2021 at 08:26:03AM -0700, Zachary Mayhew wrote:
> > > > Subject: [PATCH] staging: fbtft: add docs for fbtft_write_spi()
> > > 
> > > Odd, this shouldn't be in the body of the email :(
> > > 
> > > > 
> > > > This patch adds documentation for fbtft_write_spi() to make its
> > > > calling context clear and explain what it does.
> > > > 
> > > > Signed-off-by: Zachary Mayhew <zacklukem.kernel@gmail.com>
> > > > ---
> > > >  drivers/staging/fbtft/fbtft-io.c | 13 +++++++++++++
> > > >  1 file changed, 13 insertions(+)
> > > > 
> > > > diff --git a/drivers/staging/fbtft/fbtft-io.c b/drivers/staging/fbtft/fbtft-io.c
> > > > index de1904a443c2..985d7cf8c774 100644
> > > > --- a/drivers/staging/fbtft/fbtft-io.c
> > > > +++ b/drivers/staging/fbtft/fbtft-io.c
> > > > @@ -5,6 +5,19 @@
> > > >  #include <linux/spi/spi.h>
> > > >  #include "fbtft.h"
> > > >  
> > > > +/**
> > > > + * fbtft_write_spi() - write data to current spi
> > > > + * @par: Driver data including driver &struct spi_device
> > > > + * @buf: Buffer to write to spi
> > > > + * @len: Length of the buffer
> > > > + * Context: can sleep
> > > > + *
> > > > + * Builds an &struct spi_transfer and &struct spi_message object based on the
> > > > + * given @buf and @len.  These are then used in a call to spi_sync() which will
> > > > + * write to the spi.
> > > > + *
> > > > + * Return: zero on success or else a negative error code
> > > > + */
> > > >  int fbtft_write_spi(struct fbtft_par *par, void *buf, size_t len)
> > > >  {
> > > >  	struct spi_transfer t = {
> > > > -- 
> > > > 2.33.0
> > > > 
> > > > 
> > > 
> > > Is this file being imported into the kernel doc tools?  If so, great, if
> > > not, this isn't going to help out all that much, right?
> > 
> > It doesn't appear to be imported at this time, as such it may not be
> > necessary.
> 
> So is this change needed?

No it isn't.  Sorry for the trouble :)

> 
> thanks,
> 
> greg k-h

Thanks
-Zachary Mayhew