On Thu, 18 Mar 2021 at 05:44, Antoine Pitrou <antoine@python.org> wrote:
Le 17/03/2021 à 20:38, Victor Stinner a écrit :
There is a work-in-progress PR to document this organization: https://github.com/python/cpython/pull/24884
That's beside the point. Whether or not it's documented, it's still cumbersome to navigate because you don't know upfront in which header file you'll find the information you're looking for. So you end up switching, for example, between
Include/pystate.h,Include/cpython/pystate.handInclude/internal/pycore_pystate.h. It feels like a waste of time.
Trying to guess where symbols are defined *is* a waste of time - one of the biggest reasons I switched to VSCode as my primary text editor was because the code base search was so good.
I think it would be much more convenient with a single header file per topic, and clearly-separated sections in the header, e.g.:
The problem with this approach is that you can't tell at a glance which of the API levels a symbol belongs to - you have to scroll up in the file to find the section header to work out which section it is in.
With the directory based layout, you don't even need to click on the search result to answer that question - the file path tells you.
Cheers, Nick.
-- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia