coding_guidelines.rst: Update documentation around type annotationbschubert/mypy-docs

After
https://lists.apache.org/thread.html/r99119ddf038b3baa63afa3edf82ca28104f02550e6424dc5f14cb360%40%3Cdev.buildstream.apache.org%3E,
we now allow mypy in any part of the codebase.

- Also update previous documentation about typing public API

1 files changed, 21 insertions, 11 deletions

diff --git a/doc/source/hacking/coding_guidelines.rst b/doc/source/hacking/coding_guidelines.rst
index 0ac3bf923..156d36b42 100644
--- a/doc/source/hacking/coding_guidelines.rst
+++ b/doc/source/hacking/coding_guidelines.rst
@@ -41,21 +41,31 @@ as shown in the examples below. If a public API exists without the *Since*
 annotation, this is taken to mean that it was available since the first stable
 major point release (e.g: 2.0).
 
+We also always ensure that the **public API** is entirely typed using type
+annotations inline.
+
+The private API *can* be typed inline or in the documentation at the author's
+discretion.
+
+.. note::
+
+  Types are checked using `mypy`. You can run it like :command:`tox -e mypy`
+
 Here are some examples to get the hang of the format of API documenting
 comments and docstrings.
 
 **Public API Surface method**::
 
-  def frobnicate(self, source, *, frobilicious=False):
+  def frobnicate(self, source: Source, *, frobilicious: bool = False) -> Element:
       """Frobnicates this element with the specified source
 
       Args:
-         source (Source): The Source to frobnicate with
-         frobilicious (bool): Optionally specify that frobnication should be
+         source: The Source to frobnicate with
+         frobilicious: Optionally specify that frobnication should be
                               performed frobiliciously
 
       Returns:
-         (Element): The frobnicated version of this Element.
+         The frobnicated version of this Element.
 
       *Since: 2.2*
       """
@@ -68,14 +78,14 @@ comments and docstrings.
   # Frobnicates this element with the specified source
   #
   # Args:
-  #    source (Source): The Source to frobnicate with
-  #    frobilicious (bool): Optionally specify that frobnication should be
+  #    source: The Source to frobnicate with
+  #    frobilicious: Optionally specify that frobnication should be
   #                         performed frobiliciously
   #
   # Returns:
-  #    (Element): The frobnicated version of this Element.
+  #    The frobnicated version of this Element.
   #
-  def frobnicate(self, source, *, frobilicious=False):
+  def frobnicate(self, source: Source, *, frobilicious: bool = False) -> Element:
       ...
 
 **Public API Surface instance variable**::
@@ -118,11 +128,12 @@ comments and docstrings.
       method.
 
       Args:
-         context (Context): The invocation Context
-         count (int): The number to count
+         context: The invocation Context
+         count: The number to count
 
       *Since: 2.2*
       """
+      def __init__(self, context: Context, count: int) -> None:
       ...
 
 **Internal class**::
@@ -873,4 +884,3 @@ and then redesign the ``Scheduler`` and ``Queue`` objects to accommodate for
 the new feature and condition under which you need to dispatch a ``Job``,
 or how you can give the ``Queue`` implementation the additional context it
 needs.
-