regmap: Fixup the kernel-doc comments on functions/structures

PATCH In review Charles Keepax 2 participants 2 messages Jan 12, 2017

Subsystems (2)

Driver core Register map abstraction

lore

Share & tools

lore

Charles Keepax

author

2017-01-12 11:16 UTC #0 lore raw

PATCH 1/1 regmap: Fixup the kernel-doc comments on functions/structures

Most of the kernel-doc comments in regmap don't actually generate correctly. This patch fixes up a few common issues, corrects some typos and adds some missing argument descriptions.

The most common issues being using a : after the function name which causes the short description to not render correctly and not separating the long and short descriptions of the function. There are quite a few instances of arguments not being described or given the wrong name as well.

This patch doesn't fixup functions/structures that are currently missing descriptions.

Signed-off-by Charles Keepax <[email protected]>

---

Apologies for the giant patch, let me know if you want it split up into a patch per file or something like that, but I figured since it doesn't touch any actual code and is mostly fairly mechanical one patch seemed simplest.

Thanks,
Charles

 drivers/base/regmap/regcache.c   |  20 +++----
 drivers/base/regmap/regmap-irq.c |  62 ++++++++++---------
 drivers/base/regmap/regmap.c     | 125 +++++++++++++++++++++------------------
 include/linux/regmap.h           | 115 ++++++++++++++++++++---------------
 4 files changed, 179 insertions(+), 143 deletions(-)

drivers/base/regmap/regcache.c +10 ~~-10~~

index 4e58256..b0a0dcf 100644
@@ -224,7 +224,7 @@ void regcache_exit(struct regmap *map)
 }
 
 /**
- * regcache_read: Fetch the value of a given register from the cache.
+ * regcache_read - Fetch the value of a given register from the cache.
  *
  * @map: map to configure.
  * @reg: The register index.

@@ -255,7 +255,7 @@ int regcache_read(struct regmap *map,
 }
 
 /**
- * regcache_write: Set the value of a given register in the cache.
+ * regcache_write - Set the value of a given register in the cache.
  *
  * @map: map to configure.
  * @reg: The register index.

@@ -328,7 +328,7 @@ static int regcache_default_sync(struct regmap *map, unsigned int min,
 }
 
 /**
- * regcache_sync: Sync the register cache with the hardware.
+ * regcache_sync - Sync the register cache with the hardware.
  *
  * @map: map to configure.
  *

@@ -396,7 +396,7 @@ int regcache_sync(struct regmap *map)
 EXPORT_SYMBOL_GPL(regcache_sync);
 
 /**
- * regcache_sync_region: Sync part  of the register cache with the hardware.
+ * regcache_sync_region - Sync part  of the register cache with the hardware.
  *
  * @map: map to sync.
  * @min: first register to sync

@@ -452,7 +452,7 @@ int regcache_sync_region(struct regmap *map, unsigned int min,
 EXPORT_SYMBOL_GPL(regcache_sync_region);
 
 /**
- * regcache_drop_region: Discard part of the register cache
+ * regcache_drop_region - Discard part of the register cache
  *
  * @map: map to operate on
  * @min: first register to discard

@@ -483,10 +483,10 @@ int regcache_drop_region(struct regmap *map, unsigned int min,
 EXPORT_SYMBOL_GPL(regcache_drop_region);
 
 /**
- * regcache_cache_only: Put a register map into cache only mode
+ * regcache_cache_only - Put a register map into cache only mode
  *
  * @map: map to configure
- * @cache_only: flag if changes should be written to the hardware
+ * @enable: flag if changes should be written to the hardware
  *
  * When a register map is marked as cache only writes to the register
  * map API will only update the register cache, they will not cause

@@ -505,7 +505,7 @@ void regcache_cache_only(struct regmap *map, bool enable)
 EXPORT_SYMBOL_GPL(regcache_cache_only);
 
 /**
- * regcache_mark_dirty: Indicate that HW registers were reset to default values
+ * regcache_mark_dirty - Indicate that HW registers were reset to default values
  *
  * @map: map to mark
  *

@@ -527,10 +527,10 @@ void regcache_mark_dirty(struct regmap *map)
 EXPORT_SYMBOL_GPL(regcache_mark_dirty);
 
 /**
- * regcache_cache_bypass: Put a register map into cache bypass mode
+ * regcache_cache_bypass - Put a register map into cache bypass mode
  *
  * @map: map to configure
- * @cache_bypass: flag if changes should not be written to the cache
+ * @enable: flag if changes should not be written to the cache
  *
  * When a register map is marked with the cache bypass option, writes
  * to the register map API will only update the hardware and not the

drivers/base/regmap/regmap-irq.c +33 ~~-29~~

124 lines not on this page · raw message

drivers/base/regmap/regmap.c +69 ~~-56~~

319 lines not on this page · raw message

include/linux/regmap.h +67 ~~-48~~

312 lines not on this page · raw message

Signature · 1 line

2.1.4

Mark Brown

maintainer

2017-01-12 17:48 UTC #1 lore raw

Applied "regmap: Fixup the kernel-doc comments on functions/structures" to the regmap tree

The patch

regmap: Fixup the kernel-doc comments on functions/structures

has been applied to the regmap tree at

git://git.kernel.org/pub/scm/linux/kernel/git/broonie/regmap.git

All being well this means that it will be integrated into the linux-next tree (usually sometime in the next 24 hours) and sent to Linus during the next merge window (or sooner if it is a bug fix), however if problems are discovered then the patch may be dropped or reverted.

You may get further e-mails resulting from automated or manual testing and review of the tree, please engage with people reporting problems and send followup patches addressing any issues that are reported if needed.

If any updates are required or you are submitting further changes they should be sent as incremental updates against current git, existing patches will not be replaced.

Please add any relevant lists and maintainers to the CCs when replying to this mail.

Thanks,
Mark

Quoted 1 line

From 2cf8e2dfdf88363476f23bc600745250b94dbbed Mon Sep 17 00:00:00 2001

From: Charles Keepax <[email protected]>
Date: Thu, 12 Jan 2017 11:17:39 +0000
Subject: [PATCH] regmap: Fixup the kernel-doc comments on functions/structures