Access modifiers for callables and types

[cgranade]

Is your feature request related to a problem? Please describe.
When developing Q# libraries, it is common to introduce small functions and operations that are not intended for direct use, but which are helpful with partial application. At the moment, these functions and operations are given names starting with _ or ending with Impl, but that makes it easy to accidentally take a dependency on these functions and operations from other namespaces or compilation units.

Describe the solution you'd like
I would suggest the inclusion of an accessibility modifier attribute (or possibly multiple, depending on the level of granularity needed), paralleling the use of special-purpose keywords in other languages. In particular,

namespace Microsoft.Quantum.Core {
 
    @Attribute()
    newtype Private = Unit;

}

In code that calls a @Private() function or operation from another namespace or compilation unit, a warning could be raised indicating that about a possible accidental dependency on internal implementation details.

The new accessibility modifier attributes could also be used to simplify documentation generation logic, such that no documentation is generated for @Private() callables rather than depending on name-matching (paralleling the new @Test("…") attribute).

Describe alternatives you've considered

• The current approach could continue to be used, in which the leading underscore convention is given special meaning by the compiler and documentation generation tool. This suffers the same disadvantages as relying on *Test names for unit testing.
• New keywords (e.g.: private) could be introduced instead of new attributes.

[bettinaheim]

Thanks, @cgranade for filing this feature request! Tagging this for language impact.
As discussed, I'd love to have something like this, but it is not yet clear when we will be able to resource it.
In the meantime, it would be great to accumulate thoughts and feedback - and upvotes - from the community regarding the need(s) for this feature.

My thought so far were to make the distinction between private, internal and public, with private meaning restricting visibility to file + namespace, internal meaning the restriction to namespace + compilation unit, and public meaning the current state without any restrictions.

[bettinaheim]

Here is what we have converged to from the language design side.
Please let me know if you feel this won't meet your needs and if you have any questions or feedback.

• By default, everything will be visible everywhere, and there is no keyword planned for this case.
• We introduce a keyword "internal" that may directly precede (i.e. after any attached attributes) any operation, function or type declaration. Types and callables decorated with this keyword will be visible anywhere within the compilation unit in which they are declared.
• We introduce a keyword "private" that may directly precede any operation, function or type declaration. Types and callables decorated with this keyword will be visible only within the namespace and compilation unit in which they are declared.

General considerations:

• We do not support or plan to support combinations of access modifiers (e.g. "private internal").
• We do not plan to rely on information from the file system to interprete access modifiers now or in the future.
• Access modifiers are valid only on callable and type declarations. They specifically won't be valid on specializations or type constructors that we may introduce in the future. Specializations and constructors are subject to the same access restrictions as the parent callable or type.
• Any type used as part of a callable or type declaration needs to be equally or more accessible than the declared callable or type.
• Attributes base on private or internal types may be attached to any type or callable for which they are valid as long as they are visible at that location, independent on the accessibility of the type or callable they are attached to.