Update top level module documentation (#4893)

* Trying to avoid "types and methods" and be more descriptive.  
* Updated top level doc string.
* See go/q-stage for how this renders.

Author: dabacon

cirq-core/cirq/__init__.py

@@ -12,6 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""Cirq is a framework for creating, editing, and invoking quantum circuits."""
+
 from cirq import _import
 
 # A module can only depend on modules imported earlier in this list of modules

cirq-core/cirq/circuits/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Types and methods related to building and optimizing sequenced circuits."""
+"""Circuit classes, mutators, and outputs."""
 
 from cirq.circuits.text_diagram_drawer import (
     TextDiagramDrawer,

cirq-core/cirq/contrib/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Package for contributions.
+"""Functionality that is not part of core supported Cirq apis.
 
 Any contributions not ready for full production can be put in a subdirectory in
 this package.

cirq-core/cirq/devices/__init__.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Types for devices, device-specific qubits, and noise models."""
+"""Device classes, qubits, and topologies, as well as noise models."""
+
 from cirq.devices.device import (
     Device,
     DeviceMetadata,

cirq-core/cirq/experiments/__init__.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Package containing characterization tools and experiments."""
+"""Experiments and tools for characterizing quantum operations."""
 
 from cirq.experiments.google_v2_supremacy_circuit import (
     generate_boixo_2018_supremacy_circuits_v2,

cirq-core/cirq/interop/__init__.py

@@ -1,5 +1,17 @@
-# pylint: disable=wrong-or-nonexistent-copyright-notice
-"""Package containing code for interoperating with other quantum software."""
+# Copyright 2022 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Methods for interoperating with other quantum software."""
 
 from cirq.interop.quirk import (
     quirk_json_to_circuit,

cirq-core/cirq/ion/__init__.py

@@ -12,8 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Types for representing and methods for manipulating ion trap operations.
-"""
+"""Trapped ion devices, gates, and compiling utilties."""
 
 from cirq.ion.ion_gates import (
     ms,

cirq-core/cirq/json_resolver_cache.py

@@ -11,6 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
+"""Methods for resolving JSON types during serialization."""
 
 import functools
 from typing import Dict, TYPE_CHECKING

cirq-core/cirq/linalg/__init__.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Types and methods related to performing linear algebra.
+"""Linear algebra methods and classes useful for quantum primitives.
 
 Focuses on methods useful for analyzing and optimizing quantum circuits.
 Avoids duplicating functionality present in numpy.

cirq-core/cirq/neutral_atoms/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Device classes and tools specific to a neutral atom quantum processor."""
+"""Neutral atom devices and gates."""
 
 from cirq.neutral_atoms.neutral_atom_devices import (
     NeutralAtomDevice,

cirq-core/cirq/ops/__init__.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-"""Types for representing and methods for manipulating circuit operation trees.
+"""Gates (unitary and non-unitary), operations, base types, and gate sets.
 """
 
 from cirq.ops.arithmetic_operation import (

cirq-core/cirq/optimizers/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Circuit transformation utilities."""
+"""Classes and methods that optimize quantum circuits."""
 
 from cirq.optimizers.align_left import (
     AlignLeft,

cirq-core/cirq/protocols/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Methods and classes that define cirq's protocols."""
+"""Protocols (structural subtyping) supported in Cirq."""
 
 from cirq.protocols.act_on_protocol import (
     act_on,

cirq-core/cirq/qis/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Tools and methods for quantum information science."""
+"""Tools and methods for primitives used in quantum information science."""
 
 from cirq.qis.channels import (
     choi_to_kraus,

cirq-core/cirq/sim/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Base simulation classes and generic simulators."""
+"""Classes for circuit simulators and base implementations of these classes."""
 from typing import Tuple, Dict
 
 from cirq.sim.act_on_args import (

cirq-core/cirq/study/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Types and methods for running studies (repeated trials)."""
+"""Parameterized circuits and results."""
 
 from cirq.study.flatten_expressions import (
     ExpressionMap,

cirq-core/cirq/transformers/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Circuit transformation utilities."""
+"""Classes and methods for transforming circuits."""
 
 from cirq.transformers.analytical_decompositions import (
     compute_cphase_exponents_for_fsim_decomposition,

cirq-core/cirq/type_workarounds.py

@@ -12,7 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Module defining NotImplementedType."""
+"""Workarounds for deficiencies in python's typing system."""
+
 from typing import Any
 
 # At the moment there's no reliable way to say 'NotImplementedType'.

cirq-core/cirq/value/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Value conversion utilities and types for time and quantum states."""
+"""Value conversion utilities and classes for time and quantum states."""
 from cirq.value.abc_alt import (
     ABCMetaImplementAnyOneOf,
     alternative,

cirq-core/cirq/vis/__init__.py

@@ -12,14 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Visualization utilities."""
+"""Classes and methods for visualizing results, quantum states, and devices."""
 
 from cirq.vis.heatmap import Heatmap
+
 from cirq.vis.heatmap import TwoQubitInteractionHeatmap
 
 from cirq.vis.histogram import integrated_histogram
 
-from cirq.vis.state_histogram import get_state_histogram, plot_state_histogram
+from cirq.vis.state_histogram import (
+    get_state_histogram,
+    plot_state_histogram,
+)
+
 from cirq.vis.density_matrix import plot_density_matrix
 
 from cirq.vis.vis_utils import relative_luminance