[PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[Randy Dunlap]

Use '\' escape characters in kernel-doc notation to eliminate a warning
from Sphinx.

../drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.

Signed-off-by: Randy Dunlap <rdunlap-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org>
Cc: Doug Ledford <dledford-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
Cc: Jason Gunthorpe <jgg-VPRAkNaXOzVWk0Htik3J/w@public.gmane.org>
Cc: linux-doc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
---
 drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

--- linux-next-20171222.orig/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
+++ linux-next-20171222/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
@@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {
  * @offset: mac table starting offset
  * @num_entries: Number of entries to get or set
  * @mac_tbl_digest: mac table digest
- * @tbl_entries[]: Array of table entries
+ * @tbl_entries\[\]: Array of table entries
  *
  * The EM sends down this structure in a MAD indicating
  * the starting offset in the forwarding table that this


-- 

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[Bart Van Assche]

On 01/05/18 16:21, Randy Dunlap wrote:
> Use '\' escape characters in kernel-doc notation to eliminate a warning
> from Sphinx.
> 
> ../drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
> 
> Signed-off-by: Randy Dunlap <rdunlap-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org>
> Cc: Doug Ledford <dledford-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
> Cc: Jason Gunthorpe <jgg-VPRAkNaXOzVWk0Htik3J/w@public.gmane.org>
> Cc: linux-doc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
> ---
>   drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h |    2 +-
>   1 file changed, 1 insertion(+), 1 deletion(-)
> 
> --- linux-next-20171222.orig/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
> +++ linux-next-20171222/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
> @@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {
>    * @offset: mac table starting offset
>    * @num_entries: Number of entries to get or set
>    * @mac_tbl_digest: mac table digest
> - * @tbl_entries[]: Array of table entries
> + * @tbl_entries\[\]: Array of table entries
>    *
>    * The EM sends down this structure in a MAD indicating
>    * the starting offset in the forwarding table that this

Wouldn't it be better to fix the toolchain such that it escapes Sphinx 
metacharacters in kernel-doc headers instead of modifying the source 
code with patches like the above one?

Thanks,

Bart.
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[Dennis Dalessandro]

On 1/5/2018 7:38 PM, Bart Van Assche wrote:
> On 01/05/18 16:21, Randy Dunlap wrote:
>> Use '\' escape characters in kernel-doc notation to eliminate a warning
>> from Sphinx.
>>
>> ../drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: 
>> Inline strong start-string without end-string.
>>
>> Signed-off-by: Randy Dunlap <rdunlap-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org>
>> Cc: Doug Ledford <dledford-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>> Cc: Jason Gunthorpe <jgg-VPRAkNaXOzVWk0Htik3J/w@public.gmane.org>
>> Cc: linux-doc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>> ---
>>   drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h |    2 +-
>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>
>> --- 
>> linux-next-20171222.orig/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
>> +++ linux-next-20171222/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
>> @@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {
>>    * @offset: mac table starting offset
>>    * @num_entries: Number of entries to get or set
>>    * @mac_tbl_digest: mac table digest
>> - * @tbl_entries[]: Array of table entries
>> + * @tbl_entries\[\]: Array of table entries
>>    *
>>    * The EM sends down this structure in a MAD indicating
>>    * the starting offset in the forwarding table that this
> 
> Wouldn't it be better to fix the toolchain such that it escapes Sphinx 
> metacharacters in kernel-doc headers instead of modifying the source 
> code with patches like the above one?

I tend to agree with Bart here.

-Denny
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[Randy Dunlap]

On 01/09/18 05:46, Dennis Dalessandro wrote:
> On 1/5/2018 7:38 PM, Bart Van Assche wrote:
>> On 01/05/18 16:21, Randy Dunlap wrote:
>>> Use '\' escape characters in kernel-doc notation to eliminate a warning
>>> from Sphinx.
>>>
>>> ../drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h:243: WARNING: Inline strong start-string without end-string.
>>>
>>> Signed-off-by: Randy Dunlap <rdunlap-wEGCiKHe2LqWVfeAwA7xHQ@public.gmane.org>
>>> Cc: Doug Ledford <dledford-H+wXaHxf7aLQT0dZR+AlfA@public.gmane.org>
>>> Cc: Jason Gunthorpe <jgg-VPRAkNaXOzVWk0Htik3J/w@public.gmane.org>
>>> Cc: linux-doc-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
>>> ---
>>>   drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h |    2 +-
>>>   1 file changed, 1 insertion(+), 1 deletion(-)
>>>
>>> --- linux-next-20171222.orig/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
>>> +++ linux-next-20171222/drivers/infiniband/ulp/opa_vnic/opa_vnic_encap.h
>>> @@ -239,7 +239,7 @@ struct opa_veswport_mactable_entry {
>>>    * @offset: mac table starting offset
>>>    * @num_entries: Number of entries to get or set
>>>    * @mac_tbl_digest: mac table digest
>>> - * @tbl_entries[]: Array of table entries
>>> + * @tbl_entries\[\]: Array of table entries
>>>    *
>>>    * The EM sends down this structure in a MAD indicating
>>>    * the starting offset in the forwarding table that this
>>
>> Wouldn't it be better to fix the toolchain such that it escapes Sphinx metacharacters in kernel-doc headers instead of modifying the source code with patches like the above one?
> 
> I tend to agree with Bart here.

OK, I'll drop this patch also.

thanks,
-- 
~Randy
--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH 0/8] Infiniband: clean up kernel-doc and add driver-api chapter

[Randy Dunlap]

This patch series cleans up lots of kernel-doc notation in
drivers/infiniband/ and then adds a driver-api chapter for
Infiniband.


-- 

[PATCH 1/8] infiniband: fix ulp/opa_vnic/opa_vnic_encap.h kernel-doc for Sphinx

[Randy Dunlap]

--
To unsubscribe from this list: send the line "unsubscribe linux-rdma" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html