14. Test: Scopes

This chapter demonstrates the effect of subsection Preamble.scope in combination with the scope state stack. The goal is to render a Sphinx document for a given target audience, according to the rules defined in Scopes and visibility.

To this end, the objects of module test_scope_mix are rendered once for each target scope, each within its own section of this chapter. The scope is set at the beginning of each section using the directive .. wtrl_push_current_scope::.

The active scope determines which objects are rendered at all, and which references in the resulting HTML artifact are clickable. In this way, a consistent subgraph of the complete set of docstrings of the module is obtained.

The three sections below illustrate how the visible subset of objects changes with increasing scope.

14.1. Scope: Public

Waterloo scope context

Scope below this point is set to public.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
«Module»	test_scope_mix

Waterloo module context

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public
«Function»	f_public –⁠ from test_scope_mix

Note

Scope filter: skipped f_extension (object: extension; active: public).

Note

Scope filter: skipped f_core (object: core; active: public).

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
«Class»	X_public –⁠ from test_scope_mix

Nested classes in X_public

Public Methods in class X_public

Waterloo module context

Default module qualifier test_scope_mix ends here. No default module active.

Waterloo scope context

Scope qualifier public ends here. New current scope: public.

14.2. Scope: Extension

Waterloo scope context

Scope below this point is set to extension.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
«Module»	test_scope_mix

Waterloo module context

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public
«Function»	f_public –⁠ from test_scope_mix

Signature	test_scope_mix.f_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension function. Must reference public and extension classes in See_also for testing. Must reference public functions in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public, X_extension, f_public
«Function»	f_extension –⁠ from test_scope_mix

Note

Scope filter: skipped f_core (object: core; active: extension).

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
«Class»	X_public –⁠ from test_scope_mix

Nested classes in X_public

Preamble	scope extension normative sections Contract
Contract	general Must be constructible. constructor
«Class»	X_public.Y_extension –⁠ from test_scope_mix

Public Methods in class X_public

Signature	test_scope_mix.X_public.m_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension method.
Parameters	<empty>
Returns
Raises	<empty>
See also	f_public, f_extension
«Method»	X_public.m_extension –⁠ from test_scope_mix

Preamble	scope extension normative sections Contract, Derived from, Public classes, Public methods, See also
Contract	general Must represent an extension class. constructor Must be constructible.
Public classes	Y_core
Public methods	m_core
See also	X_public
Derived from	X_public, X_public.Y_extension
«Class»	X_extension –⁠ from test_scope_mix

Nested classes in X_extension

Public Methods in class X_extension

Waterloo module context

Default module qualifier test_scope_mix ends here. No default module active.

Waterloo scope context

Scope qualifier extension ends here. New current scope: public.

14.3. Scope: Core

Waterloo scope context

Scope below this point is set to core.

Preamble	scope public normative sections Contract, Public classes, Public functions, See also
Contract	general Must represent a public module. Must reference public classes in See_also for testing. Must reference public functions in See_also for testing.
Public classes	X_public, X_extension, X_core
Public functions	f_public, f_extension, f_core
See also	X_public, f_public
«Module»	test_scope_mix

Waterloo module context

Classes and functions below this point implicitly belong to package/module test_scope_mix.

Signature	test_scope_mix.f_public( ) -> None
Preamble	scope public normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a public function. Must reference public classes in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public
«Function»	f_public –⁠ from test_scope_mix

Signature	test_scope_mix.f_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension function. Must reference public and extension classes in See_also for testing. Must reference public functions in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public, X_extension, f_public
«Function»	f_extension –⁠ from test_scope_mix

Signature	test_scope_mix.f_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core function. Must reference public, extension, and core classes in See_also for testing. Must reference public and extension functions in See_also for testing.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public, X_extension, X_core, f_public, f_extension
«Function»	f_core –⁠ from test_scope_mix

Preamble	scope public normative sections Contract, Public classes, Public methods
Contract	general Must represent a public class. constructor Must be constructible.
Public classes	Y_extension, Y_core
Public methods	m_extension, m_core
«Class»	X_public –⁠ from test_scope_mix

Nested classes in X_public

Preamble	scope extension normative sections Contract
Contract	general Must be constructible. constructor
«Class»	X_public.Y_extension –⁠ from test_scope_mix

Preamble	scope core normative sections Contract, See also
Contract	general Must be constructible. constructor
See also	X_public.Y_extension
«Class»	X_public.Y_core –⁠ from test_scope_mix

Public Methods in class X_public

Signature	test_scope_mix.X_public.m_extension( ) -> None
Preamble	scope extension normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent an extension method.
Parameters	<empty>
Returns
Raises	<empty>
See also	f_public, f_extension
«Method»	X_public.m_extension –⁠ from test_scope_mix

Signature	test_scope_mix.X_public.m_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core method.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public.m_extension, X_public.Y_core, f_public, f_extension, f_core
«Method»	X_public.m_core –⁠ from test_scope_mix

Preamble	scope extension normative sections Contract, Derived from, Public classes, Public methods, See also
Contract	general Must represent an extension class. constructor Must be constructible.
Public classes	Y_core
Public methods	m_core
See also	X_public
Derived from	X_public, X_public.Y_extension
«Class»	X_extension –⁠ from test_scope_mix

Nested classes in X_extension

Preamble	scope core normative sections Contract, See also
Contract	general Must be constructible. constructor
See also	X_public.Y_extension, X_public.Y_core
«Class»	X_extension.Y_core –⁠ from test_scope_mix

Public Methods in class X_extension

Signature	test_scope_mix.X_extension.m_core( ) -> None
Preamble	scope core normative sections Contract, Parameters, Returns, Raises, See also
Contract	general Must represent a core method.
Parameters	<empty>
Returns
Raises	<empty>
See also	X_public.m_extension, X_public.m_core, X_extension.Y_core, f_public, f_extension, f_core
«Method»	X_extension.m_core –⁠ from test_scope_mix

Preamble	scope core normative sections Contract, See also
Contract	general Must represent a core class. constructor Must be constructible.
See also	X_public.Y_extension, X_public.Y_core, X_extension.Y_core
«Class»	X_core –⁠ from test_scope_mix

Waterloo module context

Default module qualifier test_scope_mix ends here. No default module active.

Waterloo scope context

Scope qualifier core ends here. New current scope: public.