Re: [PATCH] scripts/kernel-doc: Get -export option working again

[Jonathan Corbet <corbet@lwn.net>]

Akira Yokosawa <akiyks@gmail.com> writes:

> Jonathan Corbet wrote:
>> Akira Yokosawa <akiyks@gmail.com> writes:
>> 
>>> Jonathan Corbet wrote:
>>> [...]
>>>> Ah ... I should have thought of that ... I'm glad you did.  I've just
>>>> pushed the fix out to linux-next, will send it Linusward in the near
>>>> future.  Thanks for fixing this,
>>>
>>> Your docs-fixes is based on v6.13-rc1.
>>> This fix needs to come after v6.13-rc2.
>> 
>> ...which will happen once the fix hits mainline - the *fix* doesn't
>> depend on -rc2.
>> 
>
> Well...
> The fix conflicts semantically against v6.13-rc1.
>
> I know you hate full rebuild of htmldocs. But I'd like you to follow
> the following steps to see the full scope of this fix.
>
>  - git checkout v6.13-rc2
>  - git checkout docs-fixes
>  - make htmldocs
>
> You might be surprised, but you'll see the following:
>
> ./drivers/dma-buf/dma-buf.c:1: warning: no structured comments found
> ./drivers/iommu/iommufd/device.c:1: warning: no structured comments found
> ./drivers/iommu/iommufd/main.c:1: warning: no structured comments found
> ./drivers/counter/counter-core.c:1: warning: no structured comments found
> ./drivers/counter/counter-chrdev.c:1: warning: no structured comments found

So I guess I don't really see the problem - nobody is going to do that
(except seemingly you :)

> Current docs-fixes has a semantic conflicts opposite to the one v6.13-rc2 has.
>
> I'd really like you to send a pull request that resolves the semantic
> conflict existing in v6.13-rc2, not the one that happens to negate the
> conflict on merge.
>
> That's the minimal expectation I have.
>
> You might wonder whey you need to checkout v6.13-rc2 first and go back
> to docs-fixes to see the conflict there.
>
> That's because "make htmldocs" don't rerun kernel-doc conversion
> when only the kernel-doc script is updated.  To see the effect of
> its change, source files with affected kernel-doc comments and
> "EXPORT_SYMBOL*" need to be updated as well.
>
> Of course you are well aware of this problematic behavior of
> documentation build.

...which is worth fixing in the build system...

> I don't mind docs-mw if you'd like to keep it v6.13-rc1 based.
>
> Have I made my points clear enough for you?

I don't fully understand the problem you are concerned about, no.  But
it doesn't really matter that much, I'd rather not have an important
contributor being unhappy with me.  So I've just pulled everything
forward to -rc2 and force-pushed it; hopefully things are better now?

I'll probably send the fix upstream on Friday.

Thanks,

jon