[Intel-wired-lan] [RFC PATCH net-next v1 10/11] drivers/net/ethernet: remove incorrectly formatted doc

Jacob Keller jacob.e.keller at intel.com
Mon Sep 14 23:06:02 UTC 2020



On 9/11/2020 4:25 PM, Jesse Brandeburg wrote:
> Jacob Keller wrote:
> 
>> A lot of these look like they should probably just be converted to use
>> kdoc format instead of removing the '/**'
> 
> I understand why you're saying that, and I spent a considerable amount
> of time fixing drivers that appeared to *try* to use kdoc but messed
> up. However, if they don't have anything that looks like doxygen or
> kdoc, then I just removed the "/**" to a /* and stopped kdoc processing.
> 
> The temac driver is a good example of not actually trying to kdoc at
> all.
> 
> However I will look over the patches and see if I see @brief anywhere
> that is left and try to fix those up. I've done so much now I might as
> well finish it, but the @brief doxygen style notes had never been
> processed into kdoc before, so changing the /** into /* doesn't
> actually remove any value, just makes the build clean.
> 

Sure, I think that's important. I just wanted to point out that we are
probably breaking whoever maintained/wrote that code and used doxygen.
(Since as far as I understand, doxygen also relies on the /** to find
comments).

Basically: I think we should be clear that is what we are doing:

  "We support kdoc, not doxygen, so if you want this, use kdoc format"

Thanks,
Jake


More information about the Intel-wired-lan mailing list