#298 Add punchlines (#299)

Author: docktermj

src/senzing/szconfig.py

@@ -35,7 +35,7 @@ class SzConfig(ABC):
     @abstractmethod
     def add_data_source(self, data_source_code: str) -> str:
         """
-        The `add_data_source` method adds a data source to an existing in-memory configuration.
+        The `add_data_source` method adds a new data source to this instance.
 
         Args:
             data_source_code (str): Name of data source code to add.
@@ -62,7 +62,7 @@ def add_data_source(self, data_source_code: str) -> str:
     @abstractmethod
     def delete_data_source(self, data_source_code: str) -> str:
         """
-        The `delete_data_source` method removes a data source from an existing in-memory configuration.
+        The `delete_data_source` method deletes a data source from this instance.
 
         Args:
             data_source_code (str): Name of data source code to delete.
@@ -86,7 +86,7 @@ def delete_data_source(self, data_source_code: str) -> str:
     @abstractmethod
     def export(self) -> str:
         """
-        The `export` method creates a JSON string representation of the Senzing SzConfig object.
+        The `export` method retrieves the configuration definition for this instance.
 
         Args:
 
@@ -112,8 +112,7 @@ def export(self) -> str:
     @abstractmethod
     def get_data_sources(self) -> str:
         """
-        The `get_data_sources` method returns a JSON document of data sources
-        contained in an in-memory configuration.
+        The `get_data_sources` method gets the data sources for this instance.
 
         Args:
 
@@ -142,7 +141,7 @@ def get_data_sources(self) -> str:
 
     def help(self, method_name: str = "") -> str:
         """
-        Return the help for a particular message.
+        The `help` method returns help for a particular message.
 
         Args:
             method_name (str): The name of the method. (e.g. "init"). If empty, a list of methods and descriptions is returned.

src/senzing/szconfigmanager.py

@@ -36,8 +36,7 @@ class SzConfigManager(ABC):
     @abstractmethod
     def create_config_from_config_id(self, config_id: int) -> SzConfig:
         """
-        The `create_config_from_config_id` method creates an in-memory Senzing configuration
-        from a specific Senzing configuration stored in the Senzing database.
+        The `create_config_from_config_id` method creates a new SzConfig instance for a configuration ID.
 
         Args:
             config_id (int): The configuration identifier of the desired Senzing configuration to retrieve.
@@ -64,8 +63,7 @@ def create_config_from_config_id(self, config_id: int) -> SzConfig:
     @abstractmethod
     def create_config_from_string(self, config_definition: str) -> SzConfig:
         """
-        The `create_config_from_string` method creates an in-memory Senzing configuration
-        from the given Senzing configuration JSON document.
+        The `create_config_from_string` method creates a new SzConfig instance from a configuration definition.
 
         Args:
             config_definition (str): The Senzing configuration JSON document.
@@ -92,8 +90,10 @@ def create_config_from_string(self, config_definition: str) -> SzConfig:
     @abstractmethod
     def create_config_from_template(self) -> SzConfig:
         """
-        The `create_config_from_template` method creates an in-memory Senzing configuration
-        from the template Senzing configuration JSON document located at PIPELINE.RESOURCEPATH/templates/g2config.json
+        The `create_config_from_template` method Creates a new SzConfig instance
+        from the template configuration definition.
+
+        The template configuration is located at PIPELINE.RESOURCEPATH/templates/g2config.json
 
         Args:
             config_definition (str): The Senzing configuration JSON document.
@@ -120,7 +120,7 @@ def create_config_from_template(self) -> SzConfig:
     @abstractmethod
     def get_config_registry(self) -> str:
         """
-        The `get_config_registry` method retrieves a list of Senzing configurations from the Senzing database.
+        The `get_config_registry` method gets the configuration registry.
 
         Returns:
             str: A JSON document containing Senzing configurations.
@@ -144,7 +144,7 @@ def get_config_registry(self) -> str:
     @abstractmethod
     def get_default_config_id(self) -> int:
         """
-        The `get_default_config_id` method retrieves from the Senzing database the configuration identifier of the default Senzing configuration.
+        The `get_default_config_id` method gets the default configuration for the repository.
 
         Returns:
             int:  A configuration identifier which identifies the current configuration in use.
@@ -168,7 +168,7 @@ def get_default_config_id(self) -> int:
     @abstractmethod
     def register_config(self, config_definition: str, config_comment: str) -> int:
         """
-        The `register_config` method adds a Senzing configuration JSON document to the Senzing database.
+        The `register_config` method registers a configuration definition with the repository.
 
         Args:
             config_definition (str): The Senzing configuration JSON document.
@@ -196,7 +196,9 @@ def register_config(self, config_definition: str, config_comment: str) -> int:
     @abstractmethod
     def replace_default_config_id(self, current_default_config_id: int, new_default_config_id: int) -> None:
         """
-        The `replace_default_config_id` method replaces the old configuration identifier with a new configuration identifier in the Senzing database.
+        The `replace_default_config_id` method replaces the existing default configuration ID with a new
+        configuration ID.
+
         It is like a "compare-and-swap" instruction to serialize concurrent editing of configuration.
         If `current_default_config_id` is no longer the "current configuration identifier", the operation will fail.
         To simply set the default configuration ID, use `set_default_config_id`.
@@ -218,7 +220,9 @@ def replace_default_config_id(self, current_default_config_id: int, new_default_
     @abstractmethod
     def set_default_config(self, config_definition: str, config_comment: str) -> int:
         """
-        The `set_default_config` method replaces the current default Senzing configuration in the Senzing database.
+        The `set_default_config` method registers a configuration with the repository and sets its ID as the default
+        for the repository.
+
         To serialize modifying of the configuration identifier, see `replace_default_config_id`.
 
         Args:
@@ -244,7 +248,8 @@ def set_default_config(self, config_definition: str, config_comment: str) -> int
     @abstractmethod
     def set_default_config_id(self, config_id: int) -> None:
         """
-        The `set_default_config_id` method replaces and sets a new configuration identifier in the Senzing database.
+        The `set_default_config_id` method Sets the default configuration ID.
+
         To serialize modifying of the configuration identifier, see `replace_default_config_id`.
 
         Args:
@@ -266,7 +271,7 @@ def set_default_config_id(self, config_id: int) -> None:
 
     def help(self, method_name: str = "") -> str:
         """
-        Return the help for a particular message.
+        The `help` method returns help for a particular message.
 
         Args:
             method_name (str): The name of the method. (e.g. "init"). If empty, a list of methods and descriptions is returned.

src/senzing/szdiagnostic.py

@@ -32,7 +32,7 @@ class SzDiagnostic(ABC):
     @abstractmethod
     def check_datastore_performance(self, seconds_to_run: int) -> str:
         """
-        The `check_datastore_performance` method performs inserts to determine rate of insertion.
+        The `check_datastore_performance` method conducts a rudimentary datastore test to gauge I/O performance.
 
         Args:
             seconds_to_run (int): Duration of the test in seconds.
@@ -60,7 +60,7 @@ def check_datastore_performance(self, seconds_to_run: int) -> str:
     @abstractmethod
     def get_datastore_info(self) -> str:
         """
-        The `get_datastore_info` method returns a JSON document with details of the datastore
+        The `get_datastore_info` method returns overview information about the datastore.
         currently in use by Senzing.
 
         Raises:
@@ -82,13 +82,13 @@ def get_datastore_info(self) -> str:
     # NOTE This is experimental and for internal diagnostics, not to be documented
     @abstractmethod
     def get_feature(self, feature_id: int) -> str:  # pylint: disable=empty-docstring
-        """"""
+        """Experimental/internal for Senzing support use only."""
 
     @abstractmethod
     def purge_repository(self) -> None:
         """
         **Warning:**
-        The `purge_repository` method removes every record in the Senzing repository.
+        The `purge_repository` method purges all entity data in the entire repository.
 
         Before calling `purge_repository` all other instances of the Senzing API
         MUST be destroyed or shutdown.
@@ -108,7 +108,7 @@ def purge_repository(self) -> None:
 
     def help(self, method_name: str = "") -> str:
         """
-        Return the help for a particular message.
+        The `help` method returns help for a particular message.
 
         Args:
             method_name (str): The name of the method. (e.g. "init"). If empty, a list of methods and descriptions is returned.