[PATCH 1/2] mac80211: fix some sphinx warnings

[PATCH 1/2] mac80211: fix some sphinx warnings

[Jani Nikula]

Signed-off-by: Jani Nikula <jani.nikula@intel.com>
---
 include/net/mac80211.h | 21 +++++++++++++--------
 1 file changed, 13 insertions(+), 8 deletions(-)

diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index a810dfcb83c2..e2dba93e374f 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -811,14 +811,18 @@ enum mac80211_rate_control_flags {
  * in the control information, and it will be filled by the rate
  * control algorithm according to what should be sent. For example,
  * if this array contains, in the format { <idx>, <count> } the
- * information
+ * information::
+ *
  *    { 3, 2 }, { 2, 2 }, { 1, 4 }, { -1, 0 }, { -1, 0 }
+ *
  * then this means that the frame should be transmitted
  * up to twice at rate 3, up to twice at rate 2, and up to four
  * times at rate 1 if it doesn't get acknowledged. Say it gets
  * acknowledged by the peer after the fifth attempt, the status
- * information should then contain
+ * information should then contain::
+ *
  *   { 3, 2 }, { 2, 2 }, { 1, 1 }, { -1, 0 } ...
+ *
  * since it was transmitted twice at rate 3, twice at rate 2
  * and once at rate 1 after which we received an acknowledgement.
  */
@@ -1168,8 +1172,8 @@ enum mac80211_rx_vht_flags {
  * @rate_idx: index of data rate into band's supported rates or MCS index if
  *	HT or VHT is used (%RX_FLAG_HT/%RX_FLAG_VHT)
  * @vht_nss: number of streams (VHT only)
- * @flag: %RX_FLAG_*
- * @vht_flag: %RX_VHT_FLAG_*
+ * @flag: %RX_FLAG_\*
+ * @vht_flag: %RX_VHT_FLAG_\*
  * @rx_flags: internal RX flags for mac80211
  * @ampdu_reference: A-MPDU reference number, must be a different value for
  *	each A-MPDU but the same for each subframe within one A-MPDU
@@ -1432,7 +1436,7 @@ enum ieee80211_vif_flags {
  * @probe_req_reg: probe requests should be reported to mac80211 for this
  *	interface.
  * @drv_priv: data area for driver use, will always be aligned to
- *	sizeof(void *).
+ *	sizeof(void \*).
  * @txq: the multicast data TX queue (if driver uses the TXQ abstraction)
  */
 struct ieee80211_vif {
@@ -1743,7 +1747,7 @@ struct ieee80211_sta_rates {
  * @wme: indicates whether the STA supports QoS/WME (if local devices does,
  *	otherwise always false)
  * @drv_priv: data area for driver use, will always be aligned to
- *	sizeof(void *), size is determined in hw information.
+ *	sizeof(void \*), size is determined in hw information.
  * @uapsd_queues: bitmap of queues configured for uapsd. Only valid
  *	if wme is supported.
  * @max_sp: max Service Period. Only valid if wme is supported.
@@ -2146,12 +2150,12 @@ enum ieee80211_hw_flags {
  *
  * @radiotap_mcs_details: lists which MCS information can the HW
  *	reports, by default it is set to _MCS, _GI and _BW but doesn't
- *	include _FMT. Use %IEEE80211_RADIOTAP_MCS_HAVE_* values, only
+ *	include _FMT. Use %IEEE80211_RADIOTAP_MCS_HAVE_\* values, only
  *	adding _BW is supported today.
  *
  * @radiotap_vht_details: lists which VHT MCS information the HW reports,
  *	the default is _GI | _BANDWIDTH.
- *	Use the %IEEE80211_RADIOTAP_VHT_KNOWN_* values.
+ *	Use the %IEEE80211_RADIOTAP_VHT_KNOWN_\* values.
  *
  * @radiotap_timestamp: Information for the radiotap timestamp field; if the
  *	'units_pos' member is set to a non-negative value it must be set to
@@ -2486,6 +2490,7 @@ void ieee80211_free_txskb(struct ieee80211_hw *hw, struct sk_buff *skb);
  * in the software stack cares about, we will, in the future, have mac80211
  * tell the driver which information elements are interesting in the sense
  * that we want to see changes in them. This will include
+ *
  *  - a list of information element IDs
  *  - a list of OUIs for the vendor information element
  *
-- 
2.1.4

[PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Jani Nikula]

It's easier to manage the kernel-doc for the fields when they
documentation is next to the field.

Signed-off-by: Jani Nikula <jani.nikula@intel.com>

---

The same treatment is sorely needed for struct ieee80211_ops also, but I
don't have the time... this would get rid of the rest of the warnings in
mac80211.h.
---
 include/net/mac80211.h | 280 ++++++++++++++++++++++++++++++-------------------
 1 file changed, 173 insertions(+), 107 deletions(-)

diff --git a/include/net/mac80211.h b/include/net/mac80211.h
index e2dba93e374f..7f659c21ffba 100644
--- a/include/net/mac80211.h
+++ b/include/net/mac80211.h
@@ -2078,147 +2078,213 @@ enum ieee80211_hw_flags {
 /**
  * struct ieee80211_hw - hardware information and state
  *
- * This structure contains the configuration and hardware
- * information for an 802.11 PHY.
- *
- * @wiphy: This points to the &struct wiphy allocated for this
- *	802.11 PHY. You must fill in the @perm_addr and @dev
- *	members of this structure using SET_IEEE80211_DEV()
- *	and SET_IEEE80211_PERM_ADDR(). Additionally, all supported
- *	bands (with channels, bitrates) are registered here.
- *
- * @conf: &struct ieee80211_conf, device configuration, don't use.
- *
- * @priv: pointer to private area that was allocated for driver use
- *	along with this structure.
- *
- * @flags: hardware flags, see &enum ieee80211_hw_flags.
- *
- * @extra_tx_headroom: headroom to reserve in each transmit skb
- *	for use by the driver (e.g. for transmit headers.)
- *
- * @extra_beacon_tailroom: tailroom to reserve in each beacon tx skb.
- *	Can be used by drivers to add extra IEs.
- *
- * @max_signal: Maximum value for signal (rssi) in RX information, used
- *	only when @IEEE80211_HW_SIGNAL_UNSPEC or @IEEE80211_HW_SIGNAL_DB
- *
- * @max_listen_interval: max listen interval in units of beacon interval
- *	that HW supports
- *
- * @queues: number of available hardware transmit queues for
- *	data packets. WMM/QoS requires at least four, these
- *	queues need to have configurable access parameters.
- *
- * @rate_control_algorithm: rate control algorithm for this hardware.
- *	If unset (NULL), the default algorithm will be used. Must be
- *	set before calling ieee80211_register_hw().
- *
- * @vif_data_size: size (in bytes) of the drv_priv data area
- *	within &struct ieee80211_vif.
- * @sta_data_size: size (in bytes) of the drv_priv data area
- *	within &struct ieee80211_sta.
- * @chanctx_data_size: size (in bytes) of the drv_priv data area
- *	within &struct ieee80211_chanctx_conf.
- * @txq_data_size: size (in bytes) of the drv_priv data area
- *	within @struct ieee80211_txq.
- *
- * @max_rates: maximum number of alternate rate retry stages the hw
- *	can handle.
- * @max_report_rates: maximum number of alternate rate retry stages
- *	the hw can report back.
- * @max_rate_tries: maximum number of tries for each stage
- *
- * @max_rx_aggregation_subframes: maximum buffer size (number of
- *	sub-frames) to be used for A-MPDU block ack receiver
- *	aggregation.
- *	This is only relevant if the device has restrictions on the
- *	number of subframes, if it relies on mac80211 to do reordering
- *	it shouldn't be set.
- *
- * @max_tx_aggregation_subframes: maximum number of subframes in an
- *	aggregate an HT driver will transmit. Though ADDBA will advertise
- *	a constant value of 64 as some older APs can crash if the window
- *	size is smaller (an example is LinkSys WRT120N with FW v1.0.07
- *	build 002 Jun 18 2012).
- *
- * @max_tx_fragments: maximum number of tx buffers per (A)-MSDU, sum
- *	of 1 + skb_shinfo(skb)->nr_frags for each skb in the frag_list.
- *
- * @offchannel_tx_hw_queue: HW queue ID to use for offchannel TX
- *	(if %IEEE80211_HW_QUEUE_CONTROL is set)
- *
- * @radiotap_mcs_details: lists which MCS information can the HW
- *	reports, by default it is set to _MCS, _GI and _BW but doesn't
- *	include _FMT. Use %IEEE80211_RADIOTAP_MCS_HAVE_\* values, only
- *	adding _BW is supported today.
- *
- * @radiotap_vht_details: lists which VHT MCS information the HW reports,
- *	the default is _GI | _BANDWIDTH.
- *	Use the %IEEE80211_RADIOTAP_VHT_KNOWN_\* values.
- *
- * @radiotap_timestamp: Information for the radiotap timestamp field; if the
- *	'units_pos' member is set to a non-negative value it must be set to
- *	a combination of a IEEE80211_RADIOTAP_TIMESTAMP_UNIT_* and a
- *	IEEE80211_RADIOTAP_TIMESTAMP_SPOS_* value, and then the timestamp
- *	field will be added and populated from the &struct ieee80211_rx_status
- *	device_timestamp. If the 'accuracy' member is non-negative, it's put
- *	into the accuracy radiotap field and the accuracy known flag is set.
- *
- * @netdev_features: netdev features to be set in each netdev created
- *	from this HW. Note that not all features are usable with mac80211,
- *	other features will be rejected during HW registration.
- *
- * @uapsd_queues: This bitmap is included in (re)association frame to indicate
- *	for each access category if it is uAPSD trigger-enabled and delivery-
- *	enabled. Use IEEE80211_WMM_IE_STA_QOSINFO_AC_* to set this bitmap.
- *	Each bit corresponds to different AC. Value '1' in specific bit means
- *	that corresponding AC is both trigger- and delivery-enabled. '0' means
- *	neither enabled.
- *
- * @uapsd_max_sp_len: maximum number of total buffered frames the WMM AP may
- *	deliver to a WMM STA during any Service Period triggered by the WMM STA.
- *	Use IEEE80211_WMM_IE_STA_QOSINFO_SP_* for correct values.
- *
- * @n_cipher_schemes: a size of an array of cipher schemes definitions.
- * @cipher_schemes: a pointer to an array of cipher scheme definitions
- *	supported by HW.
- * @max_nan_de_entries: maximum number of NAN DE functions supported by the
- *	device.
+ * This structure contains the configuration and hardware information for an
+ * 802.11 PHY.
  */
 struct ieee80211_hw {
+	/**
+	 * @conf: &struct ieee80211_conf, device configuration, don't use.
+	 */
 	struct ieee80211_conf conf;
+
+	/**
+	 * @wiphy: This points to the &struct wiphy allocated for this 802.11
+	 * PHY. You must fill in the @perm_addr and @dev members of this
+	 * structure using SET_IEEE80211_DEV() and
+	 * SET_IEEE80211_PERM_ADDR(). Additionally, all supported bands (with
+	 * channels, bitrates) are registered here.
+	 */
 	struct wiphy *wiphy;
+
+	/**
+	 * @rate_control_algorithm: rate control algorithm for this hardware.
+	 * If unset (NULL), the default algorithm will be used. Must be set
+	 * before calling ieee80211_register_hw().
+	 */
 	const char *rate_control_algorithm;
+
+	/**
+	 * @priv: pointer to private area that was allocated for driver use
+	 * along with this structure.
+	 */
 	void *priv;
+
+	/**
+	 * @flags: hardware flags, see &enum ieee80211_hw_flags.
+	 */
 	unsigned long flags[BITS_TO_LONGS(NUM_IEEE80211_HW_FLAGS)];
+
+	/**
+	 * @extra_tx_headroom: headroom to reserve in each transmit skb for use
+	 * by the driver (e.g. for transmit headers.)
+	 */
 	unsigned int extra_tx_headroom;
+
+	/**
+	 * @extra_beacon_tailroom: tailroom to reserve in each beacon tx skb.
+	 * Can be used by drivers to add extra IEs.
+	 */
 	unsigned int extra_beacon_tailroom;
+
+	/**
+	 * @vif_data_size: size (in bytes) of the drv_priv data area
+	 * within &struct ieee80211_vif.
+	 */
 	int vif_data_size;
+
+	/**
+	 * @sta_data_size: size (in bytes) of the drv_priv data area within
+	 * &struct ieee80211_sta.
+	 */
 	int sta_data_size;
+
+	/**
+	 * @chanctx_data_size: size (in bytes) of the drv_priv data area within
+	 * &struct ieee80211_chanctx_conf.
+	 */
 	int chanctx_data_size;
+
+	/**
+	 * @txq_data_size: size (in bytes) of the drv_priv data area
+	 * within @struct ieee80211_txq.
+	 */
 	int txq_data_size;
+
+	/**
+	 * @queues: number of available hardware transmit queues for data
+	 * packets. WMM/QoS requires at least four, these queues need to have
+	 * configurable access parameters.
+	 */
 	u16 queues;
+
+	/**
+	 * @max_listen_interval: max listen interval in units of beacon interval
+	 * that HW supports
+	 */
 	u16 max_listen_interval;
+
+	/**
+	 * @max_signal: Maximum value for signal (rssi) in RX information, used
+	 * only when @IEEE80211_HW_SIGNAL_UNSPEC or @IEEE80211_HW_SIGNAL_DB
+	 */
 	s8 max_signal;
+
+	/**
+	 * @max_rates: maximum number of alternate rate retry stages the hw can
+	 * handle.
+	 */
 	u8 max_rates;
+
+	/**
+	 * @max_report_rates: maximum number of alternate rate retry stages
+	 * the hw can report back.
+	 */
 	u8 max_report_rates;
+
+	/**
+	 * @max_rate_tries: maximum number of tries for each stage
+	 */
 	u8 max_rate_tries;
+
+	/**
+	 * @max_rx_aggregation_subframes: maximum buffer size (number of
+	 * sub-frames) to be used for A-MPDU block ack receiver aggregation.
+	 * This is only relevant if the device has restrictions on the number of
+	 * subframes, if it relies on mac80211 to do reordering it shouldn't be
+	 * set.
+	 */
 	u8 max_rx_aggregation_subframes;
+
+	/**
+	 * @max_tx_aggregation_subframes: maximum number of subframes in an
+	 * aggregate an HT driver will transmit. Though ADDBA will advertise a
+	 * constant value of 64 as some older APs can crash if the window size
+	 * is smaller (an example is LinkSys WRT120N with FW v1.0.07 build 002
+	 * Jun 18 2012).
+	 */
 	u8 max_tx_aggregation_subframes;
+
+	/**
+	 * @max_tx_fragments: maximum number of tx buffers per (A)-MSDU, sum of
+	 * 1 + skb_shinfo(skb)->nr_frags for each skb in the frag_list.
+	 */
 	u8 max_tx_fragments;
+
+	/**
+	 * @offchannel_tx_hw_queue: HW queue ID to use for offchannel TX (if
+	 * %IEEE80211_HW_QUEUE_CONTROL is set)
+	 */
 	u8 offchannel_tx_hw_queue;
+
+	/**
+	 * @radiotap_mcs_details: lists which MCS information can the HW
+	 * reports, by default it is set to _MCS, _GI and _BW but doesn't
+	 * include _FMT. Use %IEEE80211_RADIOTAP_MCS_HAVE_\* values, only adding
+	 * _BW is supported today.
+	 */
 	u8 radiotap_mcs_details;
+
+	/**
+	 * @radiotap_vht_details: lists which VHT MCS information the HW
+	 * reports, the default is _GI | _BANDWIDTH.  Use the
+	 * %IEEE80211_RADIOTAP_VHT_KNOWN_\* values.
+	 */
 	u16 radiotap_vht_details;
+
+	/**
+	 * @radiotap_timestamp: Information for the radiotap timestamp field; if
+	 * the 'units_pos' member is set to a non-negative value it must be set
+	 * to a combination of a IEEE80211_RADIOTAP_TIMESTAMP_UNIT_* and a
+	 * IEEE80211_RADIOTAP_TIMESTAMP_SPOS_* value, and then the timestamp
+	 * field will be added and populated from the &struct
+	 * ieee80211_rx_status device_timestamp. If the 'accuracy' member is
+	 * non-negative, it's put into the accuracy radiotap field and the
+	 * accuracy known flag is set.
+	 */
 	struct {
 		int units_pos;
 		s16 accuracy;
 	} radiotap_timestamp;
+
+	/**
+	 * @netdev_features: netdev features to be set in each netdev created
+	 * from this HW. Note that not all features are usable with mac80211,
+	 * other features will be rejected during HW registration.
+	 */
 	netdev_features_t netdev_features;
+
+	/**
+	 * @uapsd_queues: This bitmap is included in (re)association frame to
+	 * indicate for each access category if it is uAPSD trigger-enabled and
+	 * delivery- enabled. Use IEEE80211_WMM_IE_STA_QOSINFO_AC_* to set this
+	 * bitmap.  Each bit corresponds to different AC. Value '1' in specific
+	 * bit means that corresponding AC is both trigger- and
+	 * delivery-enabled. '0' means neither enabled.
+	 */
 	u8 uapsd_queues;
+
+	/**
+	 * @uapsd_max_sp_len: maximum number of total buffered frames the WMM AP
+	 * may deliver to a WMM STA during any Service Period triggered by the
+	 * WMM STA. Use IEEE80211_WMM_IE_STA_QOSINFO_SP_* for correct values.
+	 */
 	u8 uapsd_max_sp_len;
+
+	/**
+	 * @n_cipher_schemes: a size of an array of cipher schemes definitions.
+	 */
 	u8 n_cipher_schemes;
+
+	/**
+	 * @cipher_schemes: a pointer to an array of cipher scheme definitions
+	 * supported by HW.
+	 */
 	const struct ieee80211_cipher_scheme *cipher_schemes;
+
+	/**
+	 * @max_nan_de_entries: maximum number of NAN DE functions supported by
+	 * the device.
+	 */
 	u8 max_nan_de_entries;
 };
 
-- 
2.1.4

Re: [PATCH 1/2] mac80211: fix some sphinx warnings

[Johannes Berg]

On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> ---
>  include/net/mac80211.h | 21 +++++++++++++--------
>  1 file changed, 13 insertions(+), 8 deletions(-)
> 
> diff --git a/include/net/mac80211.h b/include/net/mac80211.h
> index a810dfcb83c2..e2dba93e374f 100644
> --- a/include/net/mac80211.h
> +++ b/include/net/mac80211.h
> @@ -811,14 +811,18 @@ enum mac80211_rate_control_flags {
>   * in the control information, and it will be filled by the rate
>   * control algorithm according to what should be sent. For example,
>   * if this array contains, in the format { <idx>, <count> } the
> - * information
> + * information::
> 
[...]

interesting, are these not enabled by default?

I guess I'll pick up these patches, even if they probably make things
worse in my tree, since there it's still using docbook. But once we
merge everything it should be good then.

johannes

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Johannes Berg]

On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
> It's easier to manage the kernel-doc for the fields when they
> documentation is next to the field.

Hah, I wasn't even aware this was possible. Thanks!

johannes

Re: [PATCH 1/2] mac80211: fix some sphinx warnings

[Jani Nikula]

On Fri, 21 Oct 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
>> Signed-off-by: Jani Nikula <jani.nikula@intel.com>
>> ---
>>  include/net/mac80211.h | 21 +++++++++++++--------
>>  1 file changed, 13 insertions(+), 8 deletions(-)
>> 
>> diff --git a/include/net/mac80211.h b/include/net/mac80211.h
>> index a810dfcb83c2..e2dba93e374f 100644
>> --- a/include/net/mac80211.h
>> +++ b/include/net/mac80211.h
>> @@ -811,14 +811,18 @@ enum mac80211_rate_control_flags {
>>   * in the control information, and it will be filled by the rate
>>   * control algorithm according to what should be sent. For example,
>>   * if this array contains, in the format { <idx>, <count> } the
>> - * information
>> + * information::
>> 
> [...]
>
> interesting, are these not enabled by default?

rst wants indented blocks to be separated by blank lines from the
preceding and following blocks. For that you could just add the blank
lines, and it'll work.

I presumed this was nicer as preformatted/monospaced text, and for that
you'll need the "::". Up to you to have that or not.

> I guess I'll pick up these patches, even if they probably make things
> worse in my tree, since there it's still using docbook. But once we
> merge everything it should be good then.

Oh, it's built as reStructuredText in Linus' tree. Again, up to you.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 1/2] mac80211: fix some sphinx warnings

[Johannes Berg]

On Fri, 2016-10-21 at 16:14 +0300, Jani Nikula wrote:
> On Fri, 21 Oct 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> > 
> > On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
> > > 
> > > Signed-off-by: Jani Nikula <jani.nikula@intel.com>
> > > ---
> > >  include/net/mac80211.h | 21 +++++++++++++--------
> > >  1 file changed, 13 insertions(+), 8 deletions(-)
> > > 
> > > diff --git a/include/net/mac80211.h b/include/net/mac80211.h
> > > index a810dfcb83c2..e2dba93e374f 100644
> > > --- a/include/net/mac80211.h
> > > +++ b/include/net/mac80211.h
> > > @@ -811,14 +811,18 @@ enum mac80211_rate_control_flags {
> > >   * in the control information, and it will be filled by the rate
> > >   * control algorithm according to what should be sent. For
> > > example,
> > >   * if this array contains, in the format { <idx>, <count> } the
> > > - * information
> > > + * information::
> > > 
> > [...]
> > 
> > interesting, are these not enabled by default?

> rst wants indented blocks to be separated by blank lines from the
> preceding and following blocks. For that you could just add the blank
> lines, and it'll work.
> 
> I presumed this was nicer as preformatted/monospaced text, and for
> that you'll need the "::". Up to you to have that or not.

Well, I meant the warnings :)

But yeah, this is better as preformatted text. It never came out that
way with docbook either, I think, but now we can fix that.

> > I guess I'll pick up these patches, even if they probably make
> > things
> > worse in my tree, since there it's still using docbook. But once we
> > merge everything it should be good then.
> 
> Oh, it's built as reStructuredText in Linus' tree. Again, up to you.

Right. No worries. I just haven't gotten my own change back from
Linus's tree into mine, but it only means that generating the doc from
mac80211-next or net-next might be weird, which isn't a problem.

johannes

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Jani Nikula]

On Fri, 21 Oct 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
>> It's easier to manage the kernel-doc for the fields when they
>> documentation is next to the field.
>
> Hah, I wasn't even aware this was possible. Thanks!

It is indeed. And this lets you have multi-paragraph descriptions for
fields which would be impossible in the top level struct kernel-doc,
because you can't have blank lines in the field descriptions there.

Currently you can't have one line inline /** @foo: bar */ descriptions
though, the opening and closing comment markers still need to be on
their own lines. Maybe I'll get around to fixing that one of these
days...

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Arend van Spriel]

On 21-10-16 15:01, Johannes Berg wrote:
> On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
>> It's easier to manage the kernel-doc for the fields when they
>> documentation is next to the field.
> 
> Hah, I wasn't even aware this was possible. Thanks!

Me neither. I actually found it annoying to have all kernel-doc above
the type definition and indeed easy to miss fields. Now struct
ieee80211_hw is not alone and we have it all over the place in the
wireless subsystem. Is this something we want to embrace and maybe find
janitors/newbies/coccinelle-gurus to address it. Not sure if coccinelle
could deal with this.

Regards,
Arend

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Johannes Berg]

On Fri, 2016-10-21 at 20:59 +0200, Arend van Spriel wrote:
> Me neither. I actually found it annoying to have all kernel-doc above
> the type definition and indeed easy to miss fields. Now struct
> ieee80211_hw is not alone and we have it all over the place in the
> wireless subsystem. Is this something we want to embrace and maybe
> find janitors/newbies/coccinelle-gurus to address it. Not sure if
> coccinelle could deal with this.

I don't think coccinelle can look into comments, though perhaps it
could be used to *place* them - use kernel-doc script to extract them
first, and then make that output a coccinelle script to place the
comment back at the right spot?

Overall though, not sure that's worth it over just doing it by hand
once? Then again, that could be used to mass-convert more ... :)

johannes

Re: [PATCH 1/2] mac80211: fix some sphinx warnings

[Johannes Berg]

Applied.

I'll take this into the RCs so we don't have warnings there, and the
other patch into -next.

johannes

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Johannes Berg]

On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
> It's easier to manage the kernel-doc for the fields when they
> documentation is next to the field.

Ok, actually, this doesn't apply. Perhaps I'll look into scripting this
kind of conversion.

johannes

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Jani Nikula]

On Wed, 26 Oct 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
>> It's easier to manage the kernel-doc for the fields when they
>> documentation is next to the field.
>
> Ok, actually, this doesn't apply. Perhaps I'll look into scripting this
> kind of conversion.

No problem; I'll leave it up to you.

BR,
Jani.

>
> johannes

-- 
Jani Nikula, Intel Open Source Technology Center

Re: [PATCH 2/2] mac80211: use inline kernel-doc for struct ieee80211_hw

[Johannes Berg]

On Wed, 2016-10-26 at 11:36 +0300, Jani Nikula wrote:
> On Wed, 26 Oct 2016, Johannes Berg <johannes@sipsolutions.net> wrote:
> > 
> > On Fri, 2016-10-21 at 15:57 +0300, Jani Nikula wrote:
> > > 
> > > It's easier to manage the kernel-doc for the fields when they
> > > documentation is next to the field.
> > 
> > Ok, actually, this doesn't apply. Perhaps I'll look into scripting
> > this
> > kind of conversion.
> 
> No problem; I'll leave it up to you.

I'll probably end up doing it manually though - no chance I can extend
the parser to output an spatch (doing the comment placement with spatch
actually works, but getting there...)