parport: fix a kernel-doc markup

The kernel-doc markup inside share.c is actually for
__parport_register_driver. The actual goal seems to be
to document parport_register_driver().

So, fix the existing markup and add a new one.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/dc0778af8c466cc667409ead05876a5cfd3cbece.1610610937.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

diff --git a/drivers/parport/share.c b/drivers/parport/share.c
index 7fec4fe..62f8407 100644 (file)
--- a/drivers/parport/share.c
+++ b/drivers/parport/share.c
@@ -243,7 +243,7 @@ static int port_detect(struct device *dev, void *dev_drv)
 }
 
 /**
- *     parport_register_driver - register a parallel port device driver
+ *     __parport_register_driver - register a parallel port device driver
  *     @drv: structure describing the driver
  *     @owner: owner module of drv
  *     @mod_name: module name string

diff --git a/include/linux/parport.h b/include/linux/parport.h
index 1fb508c..f981f79 100644 (file)
--- a/include/linux/parport.h
+++ b/include/linux/parport.h
@@ -297,6 +297,37 @@ int __must_check __parport_register_driver(struct parport_driver *,
  * parport_register_driver must be a macro so that KBUILD_MODNAME can
  * be expanded
  */
+
+/**
+ *     parport_register_driver - register a parallel port device driver
+ *     @driver: structure describing the driver
+ *
+ *     This can be called by a parallel port device driver in order
+ *     to receive notifications about ports being found in the
+ *     system, as well as ports no longer available.
+ *
+ *     If devmodel is true then the new device model is used
+ *     for registration.
+ *
+ *     The @driver structure is allocated by the caller and must not be
+ *     deallocated until after calling parport_unregister_driver().
+ *
+ *     If using the non device model:
+ *     The driver's attach() function may block.  The port that
+ *     attach() is given will be valid for the duration of the
+ *     callback, but if the driver wants to take a copy of the
+ *     pointer it must call parport_get_port() to do so.  Calling
+ *     parport_register_device() on that port will do this for you.
+ *
+ *     The driver's detach() function may block.  The port that
+ *     detach() is given will be valid for the duration of the
+ *     callback, but if the driver wants to take a copy of the
+ *     pointer it must call parport_get_port() to do so.
+ *
+ *
+ *     Returns 0 on success. The non device model will always succeeds.
+ *     but the new device model can fail and will return the error code.
+ **/
 #define parport_register_driver(driver)             \
        __parport_register_driver(driver, THIS_MODULE, KBUILD_MODNAME)