struct device_attribute, struct dev_ext_attribute, dev_name(), and the
DEVICE_ATTR() macros lack kerneldocs, preventing them from appearing in
the driver core documentation and from being cross-referenced elsewhere.

Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
not #defined, and is aliased to DEVICE_ATTR() otherwise).

Signed-off-by: James Seo <james@equiv.tech>
---
 include/linux/device.h | 111 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 110 insertions(+), 1 deletion(-)

diff --git a/include/linux/device.h b/include/linux/device.h
index 472dd24d4823..4e59eda12c88 100644
--- a/include/linux/device.h
+++ b/include/linux/device.h
@@ -96,7 +96,12 @@ struct device_type {
 	const struct dev_pm_ops *pm;
 };
 
-/* interface for exporting device attributes */
+/**
+ * struct device_attribute - Interface for exporting device attributes.
+ * @attr: sysfs attribute definition.
+ * @show: Show handler.
+ * @store: Store handler.
+ */
 struct device_attribute {
 	struct attribute	attr;
 	ssize_t (*show)(struct device *dev, struct device_attribute *attr,
@@ -105,6 +110,11 @@ struct device_attribute {
 			 const char *buf, size_t count);
 };
 
+/**
+ * struct dev_ext_attribute - Exported device attribute with extra context.
+ * @attr: Exported device attribute.
+ * @var: Pointer to context.
+ */
 struct dev_ext_attribute {
 	struct device_attribute attr;
 	void *var;
@@ -123,30 +133,124 @@ ssize_t device_show_bool(struct device *dev, struct device_attribute *attr,
 ssize_t device_store_bool(struct device *dev, struct device_attribute *attr,
 			 const char *buf, size_t count);
 
+/**
+ * DEVICE_ATTR - Define a device attribute.
+ * @_name: Attribute name.
+ * @_mode: File mode.
+ * @_show: Show handler. Optional, but mandatory if attribute is readable.
+ * @_store: Store handler. Optional, but mandatory if attribute is writable.
+ *
+ * Convenience macro for defining a struct device_attribute.
+ *
+ * For example, ``DEVICE_ATTR(foo, 0644, foo_show, foo_store);`` expands to:
+ *
+ * .. code-block:: c
+ *
+ *	struct device_attribute dev_attr_foo = {
+ *		.attr	= { .name = "foo", .mode = 0644 },
+ *		.show	= foo_show,
+ *		.store	= foo_store,
+ *	};
+ */
 #define DEVICE_ATTR(_name, _mode, _show, _store) \
 	struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store)
+
+/**
+ * DEVICE_ATTR_PREALLOC - Define a preallocated device attribute.
+ * @_name: Attribute name.
+ * @_mode: File mode.
+ * @_show: Show handler. Optional, but mandatory if attribute is readable.
+ * @_store: Store handler. Optional, but mandatory if attribute is writable.
+ *
+ * Like DEVICE_ATTR(), but ``SYSFS_PREALLOC`` is set on @_mode.
+ */
 #define DEVICE_ATTR_PREALLOC(_name, _mode, _show, _store) \
 	struct device_attribute dev_attr_##_name = \
 		__ATTR_PREALLOC(_name, _mode, _show, _store)
+
+/**
+ * DEVICE_ATTR_RW - Define a read-write device attribute.
+ * @_name: Attribute name.
+ *
+ * Like DEVICE_ATTR(), but @_mode is 0644, @_show is <_name>_show,
+ * and @_store is <_name>_store.
+ */
 #define DEVICE_ATTR_RW(_name) \
 	struct device_attribute dev_attr_##_name = __ATTR_RW(_name)
+
+/**
+ * DEVICE_ATTR_ADMIN_RW - Define an admin-only read-write device attribute.
+ * @_name: Attribute name.
+ *
+ * Like DEVICE_ATTR_RW(), but @_mode is 0600.
+ */
 #define DEVICE_ATTR_ADMIN_RW(_name) \
 	struct device_attribute dev_attr_##_name = __ATTR_RW_MODE(_name, 0600)
+
+/**
+ * DEVICE_ATTR_RO - Define a readable device attribute.
+ * @_name: Attribute name.
+ *
+ * Like DEVICE_ATTR(), but @_mode is 0444 and @_show is <_name>_show.
+ */
 #define DEVICE_ATTR_RO(_name) \
 	struct device_attribute dev_attr_##_name = __ATTR_RO(_name)
+
+/**
+ * DEVICE_ATTR_ADMIN_RO - Define an admin-only readable device attribute.
+ * @_name: Attribute name.
+ *
+ * Like DEVICE_ATTR_RO(), but @_mode is 0400.
+ */
 #define DEVICE_ATTR_ADMIN_RO(_name) \
 	struct device_attribute dev_attr_##_name = __ATTR_RO_MODE(_name, 0400)
+
+/**
+ * DEVICE_ATTR_WO - Define an admin-only writable device attribute.
+ * @_name: Attribute name.
+ *
+ * Like DEVICE_ATTR(), but @_mode is 0200 and @_store is <_name>_store.
+ */
 #define DEVICE_ATTR_WO(_name) \
 	struct device_attribute dev_attr_##_name = __ATTR_WO(_name)
+
+/**
+ * DEVICE_ULONG_ATTR - Define a device attribute backed by an unsigned long.
+ * @_name: Attribute name.
+ * @_mode: File mode.
+ * @_var: Identifier of unsigned long.
+ *
+ * Like DEVICE_ATTR(), but @_show and @_store are automatically provided
+ * such that reads and writes to the attribute from userspace affect @_var.
+ */
 #define DEVICE_ULONG_ATTR(_name, _mode, _var) \
 	struct dev_ext_attribute dev_attr_##_name = \
 		{ __ATTR(_name, _mode, device_show_ulong, device_store_ulong), &(_var) }
+
+/**
+ * DEVICE_INT_ATTR - Define a device attribute backed by an int.
+ * @_name: Attribute name.
+ * @_mode: File mode.
+ * @_var: Identifier of int.
+ *
+ * Like DEVICE_ULONG_ATTR(), but @_var is an int.
+ */
 #define DEVICE_INT_ATTR(_name, _mode, _var) \
 	struct dev_ext_attribute dev_attr_##_name = \
 		{ __ATTR(_name, _mode, device_show_int, device_store_int), &(_var) }
+
+/**
+ * DEVICE_BOOL_ATTR - Define a device attribute backed by a bool.
+ * @_name: Attribute name.
+ * @_mode: File mode.
+ * @_var: Identifier of bool.
+ *
+ * Like DEVICE_ULONG_ATTR(), but @_var is a bool.
+ */
 #define DEVICE_BOOL_ATTR(_name, _mode, _var) \
 	struct dev_ext_attribute dev_attr_##_name = \
 		{ __ATTR(_name, _mode, device_show_bool, device_store_bool), &(_var) }
+
 #define DEVICE_ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store) \
 	struct device_attribute dev_attr_##_name =		\
 		__ATTR_IGNORE_LOCKDEP(_name, _mode, _show, _store)
@@ -700,6 +804,11 @@ static inline bool device_iommu_mapped(struct device *dev)
 /* Get the wakeup routines, which depend on struct device */
 #include <linux/pm_wakeup.h>
 
+/**
+ * dev_name - Return a device's name.
+ * @dev: Device with name to get.
+ * Return: The kobject name of the device, or its initial name if unavailable.
+ */
 static inline const char *dev_name(const struct device *dev)
 {
 	/* Use the init name until the kobject becomes available */
-- 
2.34.1

On Mon, May 08, 2023 at 08:48:50AM -0700, James Seo wrote:
> Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
> which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
> not #defined, and is aliased to DEVICE_ATTR() otherwise).
> 
> Signed-off-by: James Seo <james@equiv.tech>
> ---

I just noticed that there shouldn't be a "not" before "#defined" in the
last line of the commit message. Apologies.

On 5/8/23 09:13, James Seo wrote:
> On Mon, May 08, 2023 at 08:48:50AM -0700, James Seo wrote:
>> Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
>> which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
>> not #defined, and is aliased to DEVICE_ATTR() otherwise).
>>
>> Signed-off-by: James Seo <james@equiv.tech>
>> ---
> 
> I just noticed that there shouldn't be a "not" before "#defined" in the
> last line of the commit message. Apologies.
> 

Other than that (above), LGTM.

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>

-- 
~Randy

On Mon, May 08, 2023 at 11:55:47AM -0700, Randy Dunlap wrote:
> On 5/8/23 09:13, James Seo wrote:
>> On Mon, May 08, 2023 at 08:48:50AM -0700, James Seo wrote:
>>> Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
>>> which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
>>> not #defined, and is aliased to DEVICE_ATTR() otherwise).
>>>
>>> Signed-off-by: James Seo <james@equiv.tech>
>>> ---
>> 
>> I just noticed that there shouldn't be a "not" before "#defined" in the
>> last line of the commit message. Apologies.
>> 
> 
> Other than that (above), LGTM.
> 
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> Acked-by: Randy Dunlap <rdunlap@infradead.org>
> 
> -- 
> ~Randy

Thanks for the review!

Just to be clear, that line should read "defined, and is aliased to..."
as commit messages can't have lines that begin with '#'.

James

On Mon, May 08, 2023 at 06:51:20PM -0700, James Seo wrote:
> On Mon, May 08, 2023 at 11:55:47AM -0700, Randy Dunlap wrote:
> > On 5/8/23 09:13, James Seo wrote:
> >> On Mon, May 08, 2023 at 08:48:50AM -0700, James Seo wrote:
> >>> Add the missing kerneldocs (except for DEVICE_ATTR_IGNORE_LOCKDEP(),
> >>> which is only meaningful on debug builds with CONFIG_DEBUG_LOCK_ALLOC
> >>> not #defined, and is aliased to DEVICE_ATTR() otherwise).
> >>>
> >>> Signed-off-by: James Seo <james@equiv.tech>
> >>> ---
> >> 
> >> I just noticed that there shouldn't be a "not" before "#defined" in the
> >> last line of the commit message. Apologies.
> >> 
> > 
> > Other than that (above), LGTM.
> > 
> > Tested-by: Randy Dunlap <rdunlap@infradead.org>
> > Acked-by: Randy Dunlap <rdunlap@infradead.org>
> > 
> > -- 
> > ~Randy
> 
> Thanks for the review!
> 
> Just to be clear, that line should read "defined, and is aliased to..."
> as commit messages can't have lines that begin with '#'.

Please fix that up and send a new version please.

thanks,

greg k-h