Re: [PATCH 1/1] clk: Document of_clk_get_by_name() return values

[Dan Carpenter]

On Wed, Sep 16, 2026 at 09:28:56AM +0200, Jerome Brunet wrote:
> On mar. 15 sept. 2026 at 19:38, Dan Carpenter <error27@xxxxxxxxx> wrote:
> 
> > Callers should test the return from of_clk_get_by_name() with IS_ERR().
> > The function returns a valid clock on success and an error pointer on
> > failure; NULL is not a valid return value.
> >
> > Document this explicitly to prevent callers from treating NULL as a
> > separate failure case.
> >
> > Assisted-by: ChatGPT:gpt-5
> > Signed-off-by: Dan Carpenter <error27@xxxxxxxxx>
> > ---
> > There are a few other functions which look like they return NULL but
> > never actually do.  This is one which has caused some confusion in
> > the past.
> >
> >  drivers/clk/clk.c | 3 +++
> >  1 file changed, 3 insertions(+)
> >
> > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> > index f1756fe59372..a71bcf780de4 100644
> > --- a/drivers/clk/clk.c
> > +++ b/drivers/clk/clk.c
> > @@ -5430,6 +5430,9 @@ EXPORT_SYMBOL(of_clk_get);
> >   * This function parses the clocks and clock-names properties,
> >   * and uses them to look up the struct clk from the registered list of clock
> >   * providers.
> > + *
> > + * Returns: A clock pointer on success or an error pointer on failure.  This
> > + * function never returns NULL.
> 
> Thanks Dan. I was about to apply the change but it feels a bit strange
> to document what a function never does.
> 
> Is this a documentation that should be added everywhere the return value
> is to be tested with IS_ERR() ?
> 
> What about being more direct then:
> 
> "Returns: A clock pointer on success or an error pointer on failure.
>  Caller should test the return value with IS_ERR()"

First of all, I just want to confirm that actually it's true, right?
I've read the code but this isn't my background so I might have been
confused.

If it only returns an error pointer then, it's obvious that it should
only be tested with IS_ERR().  I would be fine with just saying the
first part:

Returns: A clock pointer on success or an error pointer on failure

regards,
dan carpenter