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

Sybren A. Stüvel sybren at blender.org
Tue Nov 16 11:02:44 CET 2021


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.

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


More information about the Bf-committers mailing list