[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