Update api module and some docs.

Fix #2.

docs/dev-guide.rst

@@ -207,7 +207,7 @@ new processors for different profiles, as shown in the example bellow.
 
 .. code-block:: python
 
-   from ini2toml import Translator
+   from ini2toml.types import Translator
 
 
    def activate(translator: Translator):
@@ -236,7 +236,7 @@ shown in the following example:
 
 .. code-block:: python
 
-   from ini2toml import Translator, Profile
+   from ini2toml.types import Translator, Profile
 
 
    def activate(translator: Translator):

src/ini2toml/api.py

@@ -1,25 +1,24 @@
-"""API available for general public usage.
+"""Public API available for general usage.
 
-The function ``activate`` in each submodule of the :obj:`ini2toml.plugins` package
-is also considered part of the public API.
+In addition to the classes and functions "exported" by this module, the following are
+also part of the public API:
+
+- The public members of the :mod:`~ini2toml.types` module.
+- The public members of the :mod:`~ini2toml.errors` module.
+- The ``activate`` function in each submodule of the :obj:`~ini2toml.plugins` package
+
+Please notice there might be classes of similar names exported by both ``api`` and
+``types``. When this happens, the classes in ``types`` are not concrete implementations,
+but instead act as :class:`protocols <typing.Protocol>` (i.e. abstract descriptions
+for checking `structural polymorphism`_ during static analysis).
+These should be preferred when writing type hints and signatures.
+
+Plugin authors can also rely on the functions exported by
+:mod:`~ini2toml.transformations`.
+
+.. _structural polymorphism: https://www.python.org/dev/peps/pep-0544/
 """
-from .plugins import ErrorLoadingPlugin
-from .translator import (
-    AlreadyRegisteredAugmentation,
-    InvalidAugmentationName,
-    Translator,
-    UndefinedProfile,
-)
-from .types import Commented, CommentedKV, CommentedList, Profile
+from . import errors, transformations, types
+from .translator import Translator
 
-__all__ = [
-    "Commented",
-    "CommentedKV",
-    "CommentedList",
-    "Translator",
-    "Profile",
-    "UndefinedProfile",
-    "InvalidAugmentationName",
-    "AlreadyRegisteredAugmentation",
-    "ErrorLoadingPlugin",
-]
+__all__ = ["Translator", "errors", "types", "transformations"]

src/ini2toml/transformations.py

@@ -79,6 +79,17 @@ def coerce_bool(value: str) -> bool:
 
 
 def coerce_scalar(value: str) -> Scalar:
+    """Try to convert the given string to a proper "scalar" type (e.g. integer, float,
+    bool, ...) with an direct TOML equivalent.
+    If the conversion is unknown or not possible, it will return the same input value
+    (as string).
+
+    .. note:: This function "guesses" the value type based in heuristics and/or regular
+       expressions, therefore there is no guarantee the output has the same type as
+       intended by the original author.
+
+    .. note:: Currently date/time-related types are not supported.
+    """
     value = value.strip()
     if value.isdecimal():
         return int(value)