Re: [PATCH] docs: driver-model: Update the documentation for device class

[Manivannan Sadhasivam]

On Sat, Apr 03, 2021 at 03:04:42PM +0200, Greg KH wrote:
> On Sat, Apr 03, 2021 at 05:30:50PM +0530, Manivannan Sadhasivam wrote:
> > The current documentation about the device class is out of date such
> > that it refers to non-existent APIs and structures. This commit updates
> > them to the current device class APIs and structures, removes wordings
> > that no longer valid while trying to keep the original content intact.
> 
> Thanks for working on this!
> 
> One thing that instantly jumped out at me:
> 
> > -Class drivers can export attributes using the DEVCLASS_ATTR macro that works
> > -similarly to the DEVICE_ATTR macro for devices. For example, a definition
> > +Class drivers can export attributes using the CLASS_ATTR_* macros that works
> > +similarly to the DEVICE_ATTR_* macros for devices. For example, a definition
> >  like this::
> >  
> > -  static DEVCLASS_ATTR(debug,0644,show_debug,store_debug);
> > +  static CLASS_ATTR_RW(debug, 0644, show_debug, store_debug);
> 
> CLASS_ATTR_RW(debug);
> is the correct way to write the above, what you added there will not
> build.
> 

Oops... I just did a blind replace there, thanks for spotting.

> But a meta-comment, should stuff like this go directly into the .c files
> itself so that the documentation is created automatically?  the fact
> that this lives so "far away" from the source ensures that it will
> always be out of date.  I know other subsystems (graphics, v4l2) have
> tied the documentation into their code files much better so I think the
> build and markup infrastructure is there today to do this.
> 

Well you're right that this documentation is far from its implementation but
that applies to most of the stuffs inside kernel, right? Also, I think if we
move these into .c file, then it will flood the whole file IMO.

We already have the kernel doc for most of the APIs/structures and that should
be enough for the .c/.h code in my perspective. If a developer wants to obtain
more information other than the API/struct definitions, then they should land
in documentation.

It should be responsibility of the maintainer to keep the doc up-to date :)

Thanks,
Mani

> thanks,
> 
> greg k-h