[Bf-committers] Change in code style guideline: location of documentation

[Sybren A. Stüvel]

On Sat, 20 Nov 2021 at 05:26, Campbell Barton <ideasman42 at gmail.com> wrote:

> > Please note that this is not a proposal to immediately start modifying
> all
> > of Blender's sources to put the docs in their new location.
>
> This sounds like header files not ending up as a good central
> reference for API's (which is one of the main benefits of the
> proposal) for as long as this is only applied to new code. Years could
> pass with many comments remaining in the implementation files instead
> of the headers.
>
> Worse, as long as they're split between both files, developers will
> need to check both the declaration and the implementation to know if a
> function has public-documentation or not.
>

I didn't want to muddle the "how do we want the code to be structured"
discussion with "when do we want to do the work" kind of discussions, or to
have it open to "but it would require so much work" counter-arguments. Now
that we have the "how" out of the way, it's indeed time for the "when".

Without pushing to migrate all doc-strings at once we could consider
> making each module team responsible for moving doc-strings into
> headers. If/when they think it's reasonable. Within a few releases (or
> less) the migration could be completed.
>

I think this is a nice approach. Not every module is equally active in
terms of development, so maybe at some point we'll have to do some
cross-module work anyway. We could create a task for each module to tackle
this, then at least we have a way to track the status.


Sybren