Re: [PATCH 1/2] clk: add kernel docs for struct clk_core

[Brian Masney <bmasney@redhat.com>]

On Tue, Mar 24, 2026 at 07:31:03PM -0700, Stephen Boyd wrote:
> Quoting Brian Masney (2026-03-04 14:51:03)
> > diff --git a/drivers/clk/clk.c b/drivers/clk/clk.c
> > index 47093cda9df32223c1120c3710261296027c4cd3..18b7a14e3f2c595d82401be9382a062fbca8a5c6 100644
> > --- a/drivers/clk/clk.c
> > +++ b/drivers/clk/clk.c
> > @@ -63,6 +63,65 @@ struct clk_parent_map {
> >         int                     index;
> >  };
> >  
> > +/**
> > + * struct clk_core - This structure represents the internal state of a clk
> > + * within the kernel's clock tree. Drivers do not interact with this structure
> > + * directly. The clk_core is manipulated by the framework to manage clock
> > + * operations, parent/child relationships, rate, and other properties.
> 
> Trim this down and use active voice please.
> 
>  /**
>   * struct clk_core - The internal state of a clk in the clk tree.
>   *
>   * Managed by the clk framework. Clk providers and consumers do not
>   * interact with this structure directly. Instead, clk operations flow
>   * through the framework and the framework manipulates this structure
>   * to keep track of parent/child relationships, rate, enable state,
>   * etc.
>   *
> 
> Does the longer paragraph description follow directly after the one line
> short description? Or does it come after all the members?

The longer paragraph goes after the description of the members.

https://docs.kernel.org/doc-guide/kernel-doc.html#function-documentation

> > + *                     initialized to clk_core->rate. It's also updated to
> > + *                     clk_core->rate every time the clock is reparented, and
> > + *                     when we're doing the orphan -> !orphan transition.
> > + * @new_rate:          New rate to be set during a rate change operation.
> > + * @new_parent:        Pointer to new parent during parent change. This is also
> > + *                     used when a clk's rate is changed.
> > + * @new_child:         Pointer to new child during reparenting. This is also
> > + *                     used when a clk's rate is changed.
> > + * @flags:             Clock property and capability flags.
> 
> Can we somehow link this to the CLK_* defines in clk-provider.h?

The kerneldoc lists how to link to things at:

https://docs.kernel.org/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext

I don't see how to link to the #defines the way it is right now, unless
we link to each one individually, which we don't want to do. We should
be able to do something like this:

enum clk_flags {
	CLK_SET_RATE_GATE   = 0,
	CLK_SET_PARENT_GATE = 1 << 0,
	CLK_SET_RATE_PARENT = 1 << 1,
	CLK_IGNORE_UNUSED   = 1 << 2,
	...
};

We could then refernece enum clk_flags in the description, and it'll
automatically link it for us. I'll try this and see how it turns out.

Brian