[PATCH 01/10] cfg80211: drop duplicated documentation of field "probe_resp_offload"

[PATCH 01/10] cfg80211: drop duplicated documentation of field "probe_resp_offload"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "probe_resp_offload" was already documented above the
definition of struct wiphy. Both comments were identical.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index f22bd6c838a3..02efea52a276 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4616,11 +4616,6 @@ struct wiphy {
 	u32 available_antennas_tx;
 	u32 available_antennas_rx;
 
-	/*
-	 * Bitmap of supported protocols for probe response offloading
-	 * see &enum nl80211_probe_resp_offload_support_attr. Only valid
-	 * when the wiphy flag @WIPHY_FLAG_AP_PROBE_RESP_OFFLOAD is set.
-	 */
 	u32 probe_resp_offload;
 
 	const u8 *extended_capabilities, *extended_capabilities_mask;
-- 
2.25.0

[PATCH 02/10] cfg80211: drop duplicated documentation of field "privid"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "privid" was already documented above the definition of struct
wiphy. Comments were not identical, but they said more or less the same
thing.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 02efea52a276..292871ae9828 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4624,11 +4624,6 @@ struct wiphy {
 	const struct wiphy_iftype_ext_capab *iftype_ext_capab;
 	unsigned int num_iftype_ext_capab;
 
-	/* If multiple wiphys are registered and you're handed e.g.
-	 * a regular netdev with assigned ieee80211_ptr, you won't
-	 * know whether it points to a wiphy your driver has registered
-	 * or not. Assign this to something global to your driver to
-	 * help determine whether you own this wiphy or not. */
 	const void *privid;
 
 	struct ieee80211_supported_band *bands[NUM_NL80211_BANDS];
-- 
2.25.0

[PATCH 03/10] cfg80211: drop duplicated documentation of field "registered"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

Field "registered" was documented three times: twice in the
documentation block of struct wiphy and once inside the struct
definition. This patch keep only one comment.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 2 --
 1 file changed, 2 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 292871ae9828..bf3bb1265bcc 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4412,7 +4412,6 @@ struct cfg80211_pmsr_capabilities {
  * @debugfsdir: debugfs directory used for this wiphy, will be renamed
  *	automatically on wiphy renames
  * @dev: (virtual) struct device for this wiphy
- * @registered: helps synchronize suspend/resume with wiphy unregister
  * @wext: wireless extension handlers
  * @priv: driver private data (sized according to wiphy_new() parameter)
  * @interface_modes: bitmask of interfaces types valid for this wiphy,
@@ -4640,7 +4639,6 @@ struct wiphy {
 	 * you need use set_wiphy_dev() (see below) */
 	struct device dev;
 
-	/* protects ->resume, ->suspend sysfs callbacks against unregister hw */
 	bool registered;
 
 	/* dir in debugfs: ieee80211/<wiphyname> */
-- 
2.25.0

[PATCH 04/10] cfg80211: drop duplicated documentation of field "_net"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "_net" was already documented above the definition of struct
wiphy. Both comments were identical.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index bf3bb1265bcc..59c8108eb756 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4649,7 +4649,6 @@ struct wiphy {
 
 	struct list_head wdev_list;
 
-	/* the network namespace this phy lives in currently */
 	possible_net_t _net;
 
 #ifdef CONFIG_CFG80211_WEXT
-- 
2.25.0

[PATCH 05/10] cfg80211: drop duplicated documentation of field "perm_addr"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "perm_addr" was already documented above the definition of
struct wiphy. Comments were almost identical.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 59c8108eb756..b5f6fe56974e 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4551,7 +4551,6 @@ struct cfg80211_pmsr_capabilities {
 struct wiphy {
 	/* assign these fields before you register the wiphy */
 
-	/* permanent MAC address(es) */
 	u8 perm_addr[ETH_ALEN];
 	u8 addr_mask[ETH_ALEN];
 
-- 
2.25.0

[PATCH 06/10] cfg80211: drop duplicated documentation of field "reg_notifier"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "reg_notifier" was already documented above the definition of
struct wiphy. The comment inside the definition of the struct did not
bring more information.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 1 -
 1 file changed, 1 deletion(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index b5f6fe56974e..4b0871eca9ef 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4626,7 +4626,6 @@ struct wiphy {
 
 	struct ieee80211_supported_band *bands[NUM_NL80211_BANDS];
 
-	/* Lets us get back the wiphy on the callback */
 	void (*reg_notifier)(struct wiphy *wiphy,
 			     struct regulatory_request *request);
 
-- 
2.25.0

[PATCH 07/10] cfg80211: merge documentations of field "debugfsdir"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "privid" is documented twice. Comments were more or less the
same. The patch merge them.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 4b0871eca9ef..2bb963e96c32 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4409,8 +4409,8 @@ struct cfg80211_pmsr_capabilities {
  *	the same number of arbitrary MAC addresses.
  * @registered: protects ->resume and ->suspend sysfs callbacks against
  *	unregister hardware
- * @debugfsdir: debugfs directory used for this wiphy, will be renamed
- *	automatically on wiphy renames
+ * @debugfsdir: debugfs directory used for this wiphy (ieee80211/<wiphyname>).
+ *	It will be renamed automatically on wiphy renames
  * @dev: (virtual) struct device for this wiphy
  * @wext: wireless extension handlers
  * @priv: driver private data (sized according to wiphy_new() parameter)
@@ -4639,7 +4639,6 @@ struct wiphy {
 
 	bool registered;
 
-	/* dir in debugfs: ieee80211/<wiphyname> */
 	struct dentry *debugfsdir;
 
 	const struct ieee80211_ht_cap *ht_capa_mod_mask;
-- 
2.25.0

[PATCH 08/10] cfg80211: merge documentations of field "dev"

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

The field "dev" was documented on two places. This patch merges the
comments.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 2bb963e96c32..1cc3442b540f 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4411,7 +4411,9 @@ struct cfg80211_pmsr_capabilities {
  *	unregister hardware
  * @debugfsdir: debugfs directory used for this wiphy (ieee80211/<wiphyname>).
  *	It will be renamed automatically on wiphy renames
- * @dev: (virtual) struct device for this wiphy
+ * @dev: (virtual) struct device for this wiphy. The item in
+ *	/sys/class/ieee80211/ points to this. You need use set_wiphy_dev()
+ *	(see below).
  * @wext: wireless extension handlers
  * @priv: driver private data (sized according to wiphy_new() parameter)
  * @interface_modes: bitmask of interfaces types valid for this wiphy,
@@ -4633,8 +4635,6 @@ struct wiphy {
 
 	const struct ieee80211_regdomain __rcu *regd;
 
-	/* the item in /sys/class/ieee80211/ points to this,
-	 * you need use set_wiphy_dev() (see below) */
 	struct device dev;
 
 	bool registered;
-- 
2.25.0

[PATCH 09/10] cfg80211: align documentation style of ieee80211_iface_combination

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

In cfg80211.h, all the structs but ieee80211_iface_combination are
documented above their definition.

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 63 +++++++++++-------------------------------
 1 file changed, 16 insertions(+), 47 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 1cc3442b540f..2f8c41993ed2 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -4103,62 +4103,31 @@ struct ieee80211_iface_limit {
  *		.num_different_channels = 2,
  *	};
  *
+ * @limits: limits for the given interface types
+ * @num_different_channels: can use up to this many different channels
+ * @max_interfaces:  maximum number of interfaces in total allowed in this group
+ * @n_limits: number of limitations
+ * @beacon_int_infra_match: In this combination, the beacon intervals between
+ *	infrastructure and AP types must match. This is required only in special
+ *	cases.
+ * @radar_detect_widths: bitmap of channel widths supported for radar detection
+ * @radar_detect_regions: bitmap of regions supported for radar detection
+ * @beacon_int_min_gcd: This interface combination supports different beacon
+ *	intervals:
+ *	    * = 0: all beacon intervals for different interface must be same.
+ *	    * > 0: any beacon interval for the interface part of this
+ *	      combination AND GCD of all beacon intervals from beaconing
+ *	      interfaces of this combination must be greater or equal to this
+ *	      value.
  */
 struct ieee80211_iface_combination {
-	/**
-	 * @limits:
-	 * limits for the given interface types
-	 */
 	const struct ieee80211_iface_limit *limits;
-
-	/**
-	 * @num_different_channels:
-	 * can use up to this many different channels
-	 */
 	u32 num_different_channels;
-
-	/**
-	 * @max_interfaces:
-	 * maximum number of interfaces in total allowed in this group
-	 */
 	u16 max_interfaces;
-
-	/**
-	 * @n_limits:
-	 * number of limitations
-	 */
 	u8 n_limits;
-
-	/**
-	 * @beacon_int_infra_match:
-	 * In this combination, the beacon intervals between infrastructure
-	 * and AP types must match. This is required only in special cases.
-	 */
 	bool beacon_int_infra_match;
-
-	/**
-	 * @radar_detect_widths:
-	 * bitmap of channel widths supported for radar detection
-	 */
 	u8 radar_detect_widths;
-
-	/**
-	 * @radar_detect_regions:
-	 * bitmap of regions supported for radar detection
-	 */
 	u8 radar_detect_regions;
-
-	/**
-	 * @beacon_int_min_gcd:
-	 * This interface combination supports different beacon intervals.
-	 *
-	 * = 0
-	 *   all beacon intervals for different interface must be same.
-	 * > 0
-	 *   any beacon interval for the interface part of this combination AND
-	 *   GCD of all beacon intervals from beaconing interfaces of this
-	 *   combination must be greater or equal to this value.
-	 */
 	u32 beacon_int_min_gcd;
 };
 
-- 
2.25.0

[PATCH 10/10] cfg80211: fix indentation errors

[Jerome Pouiller]

From: Jérôme Pouiller <jerome.pouiller@silabs.com>

Signed-off-by: Jérôme Pouiller <jerome.pouiller@silabs.com>
---
 include/net/cfg80211.h | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/include/net/cfg80211.h b/include/net/cfg80211.h
index 2f8c41993ed2..6dc642bbdbd1 100644
--- a/include/net/cfg80211.h
+++ b/include/net/cfg80211.h
@@ -72,12 +72,12 @@ struct wiphy;
  *
  * @IEEE80211_CHAN_DISABLED: This channel is disabled.
  * @IEEE80211_CHAN_NO_IR: do not initiate radiation, this includes
- * 	sending probe requests or beaconing.
+ *	sending probe requests or beaconing.
  * @IEEE80211_CHAN_RADAR: Radar detection is required on this channel.
  * @IEEE80211_CHAN_NO_HT40PLUS: extension channel above this channel
- * 	is not permitted.
+ *	is not permitted.
  * @IEEE80211_CHAN_NO_HT40MINUS: extension channel below this channel
- * 	is not permitted.
+ *	is not permitted.
  * @IEEE80211_CHAN_NO_OFDM: OFDM is not allowed on this channel.
  * @IEEE80211_CHAN_NO_80MHZ: If the driver supports 80 MHz on the band,
  *	this flag indicates that an 80 MHz channel cannot use this
@@ -1656,7 +1656,7 @@ struct mpath_info {
  * @basic_rates_len: number of basic rates
  * @ap_isolate: do not forward packets between connected stations
  * @ht_opmode: HT Operation mode
- * 	(u16 = opmode, -1 = do not change)
+ *	(u16 = opmode, -1 = do not change)
  * @p2p_ctwindow: P2P CT Window (-1 = no change)
  * @p2p_opp_ps: P2P opportunistic PS (-1 = no change)
  */
@@ -2032,8 +2032,8 @@ struct cfg80211_bss_select_adjust {
  * @ie_len: length of ie in octets
  * @flags: bit field of flags controlling operation
  * @match_sets: sets of parameters to be matched for a scan result
- * 	entry to be considered valid and to be passed to the host
- * 	(others are filtered out).
+ *	entry to be considered valid and to be passed to the host
+ *	(others are filtered out).
  *	If ommited, all results are passed.
  * @n_match_sets: number of match sets
  * @report_results: indicates that results were reported for this request
@@ -2426,7 +2426,7 @@ struct cfg80211_disassoc_request {
  *	will be used in ht_capa.  Un-supported values will be ignored.
  * @ht_capa_mask:  The bits of ht_capa which are to be used.
  * @wep_keys: static WEP keys, if not NULL points to an array of
- * 	CFG80211_MAX_WEP_KEYS WEP keys
+ *	CFG80211_MAX_WEP_KEYS WEP keys
  * @wep_tx_key: key index (0..3) of the default TX static WEP key
  */
 struct cfg80211_ibss_params {
@@ -4350,7 +4350,7 @@ struct cfg80211_pmsr_capabilities {
  *	note that if your driver uses wiphy_apply_custom_regulatory()
  *	the reg_notifier's request can be passed as NULL
  * @regd: the driver's regulatory domain, if one was requested via
- * 	the regulatory_hint() API. This can be used by the driver
+ *	the regulatory_hint() API. This can be used by the driver
  *	on the reg_notifier() if it chooses to ignore future
  *	regulatory domain changes caused by other drivers.
  * @signal_type: signal type reported in &struct cfg80211_bss.
@@ -5420,9 +5420,9 @@ void cfg80211_send_layer2_update(struct net_device *dev, const u8 *addr);
  * @wiphy: the wireless device giving the hint (used only for reporting
  *	conflicts)
  * @alpha2: the ISO/IEC 3166 alpha2 the driver claims its regulatory domain
- * 	should be in. If @rd is set this should be NULL. Note that if you
- * 	set this to NULL you should still set rd->alpha2 to some accepted
- * 	alpha2.
+ *	should be in. If @rd is set this should be NULL. Note that if you
+ *	set this to NULL you should still set rd->alpha2 to some accepted
+ *	alpha2.
  *
  * Wireless drivers can use this function to hint to the wireless core
  * what it believes should be the current regulatory domain by
-- 
2.25.0

Re: [PATCH 09/10] cfg80211: align documentation style of ieee80211_iface_combination

[Johannes Berg]

On Fri, 2020-02-21 at 12:56 +0100, Jerome Pouiller wrote:
> 
> + *	intervals:
> + *	    * = 0: all beacon intervals for different interface must be same.
> + *	    * > 0: any beacon interval for the interface part of this
> + *	      combination AND GCD of all beacon intervals from beaconing
> + *	      interfaces of this combination must be greater or equal to this
> + *	      value.

Hmm. I have a feeling I actually split this one out because

> -	 * = 0
> -	 *   all beacon intervals for different interface must be same.
> -	 * > 0
> -	 *   any beacon interval for the interface part of this combination AND
> -	 *   GCD of all beacon intervals from beaconing interfaces of this
> -	 *   combination must be greater or equal to this value.

This generates the nicer output, not with bullets but as a definition
list or something.

johannes

Re: [PATCH 09/10] cfg80211: align documentation style of ieee80211_iface_combination

[Jérôme Pouiller]

On Friday 21 February 2020 13:02:20 CET Johannes Berg wrote:
> CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.
> 
> 
> On Fri, 2020-02-21 at 12:56 +0100, Jerome Pouiller wrote:
> >
> > + *   intervals:
> > + *       * = 0: all beacon intervals for different interface must be same.
> > + *       * > 0: any beacon interval for the interface part of this
> > + *         combination AND GCD of all beacon intervals from beaconing
> > + *         interfaces of this combination must be greater or equal to this
> > + *         value.
> 
> Hmm. I have a feeling I actually split this one out because
> 
> > -      * = 0
> > -      *   all beacon intervals for different interface must be same.
> > -      * > 0
> > -      *   any beacon interval for the interface part of this combination AND
> > -      *   GCD of all beacon intervals from beaconing interfaces of this
> > -      *   combination must be greater or equal to this value.
> 
> This generates the nicer output, not with bullets but as a definition
> list or something.
Indeed.

Unfortunately, I hasn't been able to use the same syntax in struct
description: if sphinx find a blank line, it considers that the rest of
the input is the long description of the struct.

-- 
Jérôme Pouiller

Re: [PATCH 09/10] cfg80211: align documentation style of ieee80211_iface_combination

[Johannes Berg]

On Fri, 2020-02-21 at 12:38 +0000, Jérôme Pouiller wrote:
> 
> > > -      * = 0
> > > -      *   all beacon intervals for different interface must be same.
> > > -      * > 0
> > > -      *   any beacon interval for the interface part of this combination AND
> > > -      *   GCD of all beacon intervals from beaconing interfaces of this
> > > -      *   combination must be greater or equal to this value.
> > 
> > This generates the nicer output, not with bullets but as a definition
> > list or something.
> Indeed.
> 
> Unfortunately, I hasn't been able to use the same syntax in struct
> description: if sphinx find a blank line, it considers that the rest of
> the input is the long description of the struct.

So let's just leave it as is. I don't consider using the same style
(inline or header) everywhere to be even nearly as important as the
output :)

johannes

Re: [PATCH 09/10] cfg80211: align documentation style of ieee80211_iface_combination

[Jérôme Pouiller]

On Friday 21 February 2020 13:41:34 CET Johannes Berg wrote:
> CAUTION: This email originated from outside of the organization. Do not click links or open attachments unless you recognize the sender and know the content is safe.
> 
> 
> On Fri, 2020-02-21 at 12:38 +0000, Jérôme Pouiller wrote:
> >
> > > > -      * = 0
> > > > -      *   all beacon intervals for different interface must be same.
> > > > -      * > 0
> > > > -      *   any beacon interval for the interface part of this combination AND
> > > > -      *   GCD of all beacon intervals from beaconing interfaces of this
> > > > -      *   combination must be greater or equal to this value.
> > >
> > > This generates the nicer output, not with bullets but as a definition
> > > list or something.
> > Indeed.
> >
> > Unfortunately, I hasn't been able to use the same syntax in struct
> > description: if sphinx find a blank line, it considers that the rest of
> > the input is the long description of the struct.
> 
> So let's just leave it as is. I don't consider using the same style
> (inline or header) everywhere to be even nearly as important as the
> output :)
Ok.

Alternatively, the following syntax generate an output close to the
original:

    *   intervals:
    *       := 0: all beacon intervals for different interface must be same.
    *       :> 0: any beacon interval for the interface part of this
    *         combination AND GCD of all beacon intervals from beaconing
    *         interfaces of this combination must be greater or equal to this
    *         value.

-- 
Jérôme Pouiller