Improve segment.py (#785)

* Add and revise documentation.

* Corrected return directives.

* Minor documentation improvements.

* Add class docstring and minor corrections.

---------

Co-authored-by: knutnergaard <knutnergaard@users.noreply.github.com>

Lib/fontParts/base/segment.py

@@ -35,6 +35,8 @@ class BaseSegment(
     DeprecatedSegment,
     RemovedSegment,
 ):
+    """Represent the basis for a segment object."""
+
     def _setPoints(self, points: CollectionType[BasePoint]) -> None:
         if hasattr(self, "_points"):
             raise AssertionError("segment has points")