On Tue, Nov 16, 2021 at 9:03 PM Sybren A. Stüvel via Bf-committers <bf-committers@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@blender.org > List details, subscription details or unsubscribe: > https://lists.blender.org/mailman/listinfo/bf-committers -- - Campbell _______________________________________________ Bf-committers mailing list Bf-committers@blender.org List details, subscription details or unsubscribe: https://lists.blender.org/mailman/listinfo/bf-committers