[RFC PATCH v7 3/8] dpll: documentation on DPLL subsystem interface

[Jakub Kicinski]

On Fri, 5 May 2023 14:16:53 +0100 Vadim Fedorenko wrote:
> >> +Then there are two groups of configuration knobs:
> >> +1) Set on a pin - the configuration affects all dpll devices pin is
> >> +   registered to. (i.e. ``PIN_FREQUENCY``, ``PIN_DIRECTION``),  
> > 
> > Why is direction set on a pin? We can't chain DPLLs?  
> 
> We can chain DPLLs using pins only. We don't have any interface to
> configure 2 pins to connect 2 different DPLLs to each other at the same 
> time. The configuration should take care of one pin being input and
> other one being output. That's why we have direction property attached
> to the pin, not the DPLL itself.

Makes sense.

> >> +Device driver implementation
> >> +============================
> >> +
> >> +Device is allocated by ``dpll_device_get`` call. Second call with the
> >> +same arguments doesn't create new object but provides pointer to
> >> +previously created device for given arguments, it also increase refcount
> >> +of that object.
> >> +Device is deallocated by ``dpll_device_put`` call, which first decreases
> >> +the refcount, once refcount is cleared the object is destroyed.  
> > 
> > You can add () after the function name and render the kdoc at the end
> > of this doc. The `` marking will then be unnecessary.
> >   
> Mmm... any examples of such a way of creating documentation? I was
> following tls*.rst style, but without copying code-blocks.

net_dim.rst, maybe?  driver.rst ? Feel free to ping me 1:1 if you're
struggling, it should be fairly straightforward.