Re: [PATCH] USB: drop misleading usb_set_intfdata() kernel doc

[Alan Stern <stern@rowland.harvard.edu>]

On Mon, Dec 12, 2022 at 05:08:17PM +0100, Johan Hovold wrote:
> The fact that USB core and driver core clears the pointer is an
> implementation detail which in principle could change.

With the new kerneldoc, the fact that the USB core clears the pointer 
becomes part of the API.  It is no longer an implementation detail but 
rather a guarantee that drivers can depend on.  (I.e., if it does 
change, all the USB drivers will need to be audited.)

>  The important
> part is that drivers generally should not touch the struct device or
> containing structure after unbind (and must do so with care otherwise).

While that certainly is an important point, it is not the point of 
usb_set_intfdata() or its kerneldoc.  The main reason for adding the 
kerneldoc -- Vincent's original motivation -- was to inform coders that 
drivers generally don't need to worry about clearing the data pointer.

A subtext was that clearing the pointer while the driver is still using 
it can lead to problems, but I don't think we need to mention this.  
It's pretty obvious.

Alan Stern