fill out some docstrings

src/python/pants/backend/native/config/environment.py

@@ -53,7 +53,7 @@ class ExtensibleAlgebraic(object):
   @abstractmethod
   def copy(self, **kwargs):
     """Analogous to a `datatype()`'s `copy()` method."""
-    raise NotImplementedError('???')
+    raise NotImplementedError('copy() must be implemented by subclasses of ExtensibleAlgebraic!')
 
   def _single_list_field_operation(self, field_name, list_value, prepend=True):
     cur_value = getattr(self, field_name)
@@ -67,17 +67,20 @@ def _single_list_field_operation(self, field_name, list_value, prepend=True):
     return self.copy(**arg_dict)
 
   def prepend_field(self, field_name, list_value):
+    """Return a copy of this object with `list_value` prepended to the field named `field_name`."""
     return self._single_list_field_operation(field_name, list_value, prepend=True)
 
   def append_field(self, field_name, list_value):
+    """Return a copy of this object with `list_value` appended to the field named `field_name`."""
     return self._single_list_field_operation(field_name, list_value, prepend=False)
 
   def sequence(self, other, exclude_list_fields=None):
-    """
-    - the return type is the type of this object (or just whatever .copy() does!)
-      - but the `other` can be any `ExtensibleAlgebraic`
-    - for this particular operation: "add" all of the list_fields together, for the fields common to
-      both types
+    """Return a copy of this object which combines all the fields common to both `self` and `other`.
+
+    List fields will be concatenated.
+
+    The return type of this method is the type of `self`, but the `other` can be any
+    `ExtensibleAlgebraic` instance.
     """
     exclude_list_fields = exclude_list_fields or []
     overwrite_kwargs = {}
@@ -108,20 +111,20 @@ def path_entries(self):
 
     This may be multiple directories, e.g. if the main executable program invokes any subprocesses.
     """
-    raise NotImplementedError('???')
+    raise NotImplementedError('path_entries is a list field of Executable!')
 
   @abstractproperty
   def library_dirs(self):
     """Directories containing shared libraries that must be on the runtime library search path.
 
     Note: this is for libraries needed for the current Executable to run -- see LinkerMixin below
     for libraries that are needed at link time."""
-    raise NotImplementedError('???')
+    raise NotImplementedError('library_dirs is a list field of Executable!')
 
   @abstractproperty
   def exe_filename(self):
     """The "entry point" -- which file to invoke when PATH is set to `path_entries()`."""
-    raise NotImplementedError('???')
+    raise NotImplementedError('exe_filename is a scalar field of Executable!')
 
   @abstractproperty
   def extra_args(self):
@@ -130,7 +133,7 @@ def extra_args(self):
     Typically, these arguments are placed before any invocation-specific arguments on the command
     line.
     """
-    raise NotImplementedError('???')
+    raise NotImplementedError('extra_args is a list field of Executable!')
 
   _platform = Platform.create()
 
@@ -164,7 +167,7 @@ def list_fields(cls):
   @abstractproperty
   def linking_library_dirs(self):
     """Directories to search for libraries needed at link time."""
-    raise NotImplementedError('???')
+    raise NotImplementedError('linking_library_dirs is a list field of LinkerMixin!')
 
   @property
   def as_invocation_environment_dict(self):
@@ -196,7 +199,7 @@ def list_fields(cls):
   @abstractproperty
   def include_dirs(self):
     """Directories to search for header files to #include during compilation."""
-    raise NotImplementedError('???')
+    raise NotImplementedError('include_dirs is a list field of Executable!')
 
   @property
   def as_invocation_environment_dict(self):