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

[Campbell Barton]

On Tue, Nov 16, 2021 at 9:03 PM Sybren A. Stüvel via Bf-committers
<bf-committers at blender.org> wrote:
>
> Hi all,
>
> Recently there has been a discussion about the location of code
> documentation (as in, the in-source documentation comments). The gist of it
> is that, in my opinion, documentation of the public interface of some
> module should be done in its header file. This promotes black-boxing, and
> gives a nice overview of how to use the code without having to dive into
> the implementation details.
>
> For a more thorough description, and to join in the discussion, please
> visit https://developer.blender.org/T92709
>
> If you agree with the proposal, please leave a thumbs-up token. If not,
> please suggest how we can improve the proposal. Do that on the task itself,
> though, and not here on the mailing list, so that we have all the
> discussions in one place.
>
> 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 guideline
> would be in effect for new code, and can be handled as well for existing
> code when people work on it.

Since T92709  doesn't cover migration to the new convention, replying
here as I don't think what's being proposed is ideal.

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.

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.

> If there are no major objections / adjustments, I want to put the new
> guideline in effect in a week. That should give us plenty of time to get
> the details right.
>
> Cheers,
> Sybren
> _______________________________________________
> Bf-committers mailing list
> Bf-committers at blender.org
> List details, subscription details or unsubscribe:
> https://lists.blender.org/mailman/listinfo/bf-committers



-- 
- Campbell