Previously, we said this must be true:

Its definition’s docstring is marked API public, and its enclosing definition, if any, is part of the public API.

We then give an example:

a method baz of class Bar defined at the top level of module foo is part of the public API if and only if the docstrings of foo, Bar and baz are all marked API public

-- I don’t think we’ve been following that for a long time. It’s rare to find a module annotated

:API public

. That would imply that almost none of Pants is actually public, which I don’t think we intend. Also, I don’t think it makes a ton of sense. What does it mean to mark a method as public API, but for its enclosing class to be private? Per the policy, the method would actually be private - so why add the annotation to the method? -- Instead, I propose this reword:

A module, variable, method, function, or class is part of the public API if at least one of the following is true:

* Its definition’s docstring is marked with API public.

* Its enclosing scope is marked with API public and the name does not start with an underscore.

* It is abstract and any inheriting class published by Pants is marked API public.

iirc, John had had thoughts on the prior definition, and had made the most recent edits there.