Updates to doc strings

Punctuation, capitalization, other updates.

Author: mtevenan-splunk

splunklib/modularinput/__init__.py

@@ -20,16 +20,16 @@
 class Argument(object):
     """Class representing an argument to a modular input kind.
 
-    Argument is meant to be used with Scheme to generate an XML definition of the modular input
-    kind that Splunk understands.
+    ``Argument`` is meant to be used with ``Scheme`` to generate an XML 
+    definition of the modular input kind that Splunk understands.
 
-    name is the only required parameter for the constructor
+    ``name`` is the only required parameter for the constructor.
 
-        Example with least parameters:
+        **Example with least parameters**::
 
             arg1 = Argument(name="arg1")
 
-        Example with all parameters:
+        **Example with all parameters**::
 
             arg2 = Argument(
                 name="arg2",
@@ -50,14 +50,14 @@ class Argument(object):
     def __init__(self, name, description=None, validation=None,
                  data_type=data_type_string, required_on_edit=False, required_on_create=False):
         """
-        :param name: string, identifier for this argument in Splunk
-        :param description: string, human readable description of the argument
-        :param validation: string, specifying how the argument should be validated, if using internal validation.
+        :param name: ``string``, identifier for this argument in Splunk.
+        :param description: ``string``, human-readable description of the argument.
+        :param validation: ``string`` specifying how the argument should be validated, if using internal validation.
         If using external validation, this will be ignored.
-        :param data_type: string, data type of this field; use the class constants
-        data_type_boolean, data_type_number, or data_type_string
-        :param required_on_edit: boolean, is this arg required when editing an existing modular input of this kind?
-        :param required_on_create: boolean, is this arg required when creating a modular input of this kind?
+        :param data_type: ``string``, data type of this field; use the class constants.
+        "data_type_boolean", "data_type_number", or "data_type_string".
+        :param required_on_edit: ``Boolean``, whether this arg is required when editing an existing modular input of this kind.
+        :param required_on_create: ``Boolean``, whether this arg is required when creating a modular input of this kind.
         """
         self.name = name
         self.description = description
@@ -67,13 +67,13 @@ def __init__(self, name, description=None, validation=None,
         self.required_on_create = required_on_create
 
     def add_to_document(self, parent):
-        """Add an Argument object to this ElementTree Document
+        """Adds an ``Argument`` object to this ElementTree document.
 
-        Adds an <arg> SubElement to the Parent Element, typically <args>
-        and setup its subelements with their respective text
+        Adds an <arg> subelement to the parent element, typically <args>
+        and sets up its subelements with their respective text.
 
-        :param parent: an ET.Element to be the parent of a new <arg> SubElement
-        :return: an ET.Element object representing this argument #TODO: might not need to return here..
+        :param parent: An ``ET.Element`` to be the parent of a new <arg> subelement
+        :returns: An ``ET.Element`` object representing this argument. #TODO: might not need to return here..
         """
         arg = ET.SubElement(parent, "arg")
         arg.set("name", self.name)

splunklib/modularinput/argument.py

@@ -20,21 +20,21 @@
 class Event(object):
     """Represents an event or fragment of an event to be written by this modular input to Splunk.
 
-    To write an input to a stream, call the write_to function, passing in a stream.
+    To write an input to a stream, call the ``write_to`` function, passing in a stream.
     """
     def __init__(self, data=None, stanza=None, time=None, host=None, index=None, source=None,
                  sourcetype=None, done=True, unbroken=True):
         """There are no required parameters for constructing an Event
 
-        Example with minimal configuration:
+        **Example with minimal configuration**::
 
             my_event = Event(
                 data="This is a test of my new event.",
                 stanza="myStanzaName",
                 time="%.3f" % 1372187084.000
             )
 
-        Example with full configuration:
+        **Example with full configuration**::
 
             excellent_event = Event(
                 data="This is a test of my excellent event.",
@@ -48,15 +48,15 @@ def __init__(self, data=None, stanza=None, time=None, host=None, index=None, sou
                 unbroken=True
             )
 
-        :param data: string, the event's text
-        :param stanza: string, name of the input this event should be sent to
-        :param time: float, time in seconds, including up to 3 decimal places to represent milliseconds
-        :param host: string, the event's host, ex: localhost
-        :param index: string, the index this event is specified to write to, or None if default index
-        :param source: string, the source of this event, or None to have Splunk guess
-        :param sourcetype: string, source type currently set on this event, or None to have Splunk guess
-        :param done: boolean, is this a complete Event? False if an Event fragment
-        :param unbroken: boolean, Is this event completely encapsulated in this Event object?
+        :param data: ``string``, the event's text.
+        :param stanza: ``string``, name of the input this event should be sent to.
+        :param time: ``float``, time in seconds, including up to 3 decimal places to represent milliseconds.
+        :param host: ``string``, the event's host, ex: localhost.
+        :param index: ``string``, the index this event is specified to write to, or None if default index.
+        :param source: ``string``, the source of this event, or None to have Splunk guess.
+        :param sourcetype: ``string``, source type currently set on this event, or None to have Splunk guess.
+        :param done: ``boolean``, is this a complete ``Event``? False if an ``Event`` fragment.
+        :param unbroken: ``boolean``, Is this event completely encapsulated in this ``Event`` object?
         """
         self.data = data
         self.done = done
@@ -69,12 +69,12 @@ def __init__(self, data=None, stanza=None, time=None, host=None, index=None, sou
         self.unbroken = unbroken
 
     def write_to(self, stream):
-        """Write an XML representation of self, an Event object, to the given stream
+        """Write an XML representation of self, an ``Event`` object, to the given stream.
 
-        The Event object will only be written if its data field is defined,
-        otherwise a ValueError is raised.
+        The ``Event`` object will only be written if its data field is defined,
+        otherwise a ``ValueError`` is raised.
 
-        :param stream: stream to write XML to
+        :param stream: stream to write XML to.
         """
         if self.data is None:
             raise ValueError("Events must have at least the data field set to be written to XML.")

splunklib/modularinput/event.py

@@ -22,10 +22,10 @@
     from StringIO import StringIO
 
 class EventWriter(object):
-    """EventWriter writes events and error messages to Splunk from a modular input.
+    """``EventWriter`` writes events and error messages to Splunk from a modular input.
 
-    Its two important methods are writeEvent, which takes an Event object,
-    and log, which takes a severity and an error message.
+    Its two important methods are ``writeEvent``, which takes an ``Event`` object,
+    and ``log``, which takes a severity and an error message.
     """
 
     # Severities that Splunk understands for log messages from modular inputs.
@@ -38,8 +38,8 @@ class EventWriter(object):
 
     def __init__(self, output = sys.stdout, error = sys.stderr):
         """
-        :param output: where to write the output, defaults to sys.stdout
-        :param error: where to write any errors, defaults to sys.stderr
+        :param output: Where to write the output; defaults to sys.stdout.
+        :param error: Where to write any errors; defaults to sys.stderr.
         """
         self._out = output
         self._err = error
@@ -48,9 +48,9 @@ def __init__(self, output = sys.stdout, error = sys.stderr):
         self.header_written = False
 
     def write_event(self, event):
-        """Write an Event object to Splunk.
+        """Writes an ``Event`` object to Splunk.
 
-        :param event: an Event object
+        :param event: An ``Event`` object.
         """
 
         if not self.header_written:
@@ -60,21 +60,21 @@ def write_event(self, event):
         event.write_to(self._out)
 
     def log(self, severity, message):
-        """Log messages about the state of this modular input to Splunk.
-        These messages will show up in Splunk's internal logs
+        """Logs messages about the state of this modular input to Splunk.
+        These messages will show up in Splunk's internal logs.
 
-        :param severity: string, severity of message, see severites defined as class constants
-        :param message: message to log
+        :param severity: ``string``, severity of message, see severites defined as class constants.
+        :param message: Message to log.
         """
 
         self._err.write("%s %s\n" % (severity, message))
         self._err.flush()
 
     def write_xml_document(self, document):
-        """Write a string representation of an
-        ElementTree object to the output stream
+        """Writes a string representation of an
+        ``ElementTree`` object to the output stream.
 
-        :param document: an ElementTree object
+        :param document: An ``ElementTree`` object.
         """
         self._out.write(ET.tostring(document, "utf-8", "xml"))
         self._out.flush()

splunklib/modularinput/event_writer.py

@@ -1,3 +1,5 @@
+# Copyright 2011-2013 Splunk, Inc.
+#
 # Licensed under the Apache License, Version 2.0 (the "License"): you may
 # not use this file except in compliance with the License. You may obtain
 # a copy of the License at
@@ -18,8 +20,8 @@
 from utils import parse_xml_data
 
 class InputDefinition:
-    """InputDefinition encodes the XML defining inputs that Splunk passes to
-    a modular input script
+    """``InputDefinition`` encodes the XML defining inputs that Splunk passes to
+    a modular input script.
 
      **Example**::
 
@@ -37,10 +39,10 @@ def __eq__(self, other):
 
     @staticmethod
     def parse(stream):
-        """Parse a stream containing XML into an InputDefinition.
+        """Parse a stream containing XML into an ``InputDefinition``.
 
-        :param stream: stream containing XML to parse
-        :return: definition: a InputDefinition object
+        :param stream: stream containing XML to parse.
+        :return: definition: an ``InputDefinition`` object.
         """
         definition = InputDefinition()
 

splunklib/modularinput/input_definition.py

@@ -20,10 +20,10 @@
 class Scheme(object):
     """Class representing the metadata for a modular input kind.
 
-    A Scheme specifies a title, description, several options of how Splunk should run modular inputs of this
+    A ``Scheme`` specifies a title, description, several options of how Splunk should run modular inputs of this
     kind, and a set of arguments which define a particular modular input's properties.
 
-    The primary use of Scheme is to abstract away the construction of XML to feed to Splunk.
+    The primary use of ``Scheme`` is to abstract away the construction of XML to feed to Splunk.
     """
 
     # Constant values, do not change
@@ -33,7 +33,7 @@ class Scheme(object):
 
     def __init__(self, title):
         """
-        :param title: string identifier for this Scheme in Splunk
+        :param title: ``string`` identifier for this Scheme in Splunk.
         """
         self.title = title
         self.description = None
@@ -45,16 +45,16 @@ def __init__(self, title):
         self.arguments = []
 
     def add_argument(self, arg):
-        """Add the provided argument, arg, to the self.arguments list
+        """Add the provided argument, ``arg``, to the ``self.arguments`` list.
 
-        :param arg: an Argument object to add to self.arguments
+        :param arg: An ``Argument`` object to add to ``self.arguments``.
         """
         self.arguments.append(arg)
 
     def to_xml(self):
-        """Creates an ET.Element representing self, then returns it
+        """Creates an ``ET.Element`` representing self, then returns it.
 
-        :return root, an ET.Element representing this scheme
+        :returns root, an ``ET.Element`` representing this scheme.
         """
         root = ET.Element("scheme")
 

splunklib/modularinput/scheme.py

@@ -28,20 +28,20 @@
 class Script(object):
     """An abstract base class for implementing modular inputs.
 
-    Subclasses should override get_scheme, stream_events,
-    and optionally validate_input if the modular Input uses
+    Subclasses should override ``get_scheme``, ``stream_events``,
+    and optionally ``validate_input`` if the modular input uses
     external validation.
 
-    The run function is used to run modular inputs, it typically should
+    The ``run`` function is used to run modular inputs; it typically should
     not be overridden.
     """
     __metaclass__ = ABCMeta
 
     def run(self, args):
-        """Run this modular input
+        """Runs this modular input
 
-        :param args: list of command line arguments passed to this script
-        :return: an integer to be used as the exit value of this program
+        :param args: List of command line arguments passed to this script.
+        :returns: An integer to be used as the exit value of this program.
         """
 
         # call the run_script function, which handles the specifics of running
@@ -51,10 +51,10 @@ def run(self, args):
     def run_script(self, args, event_writer, input_stream):
         """Handles all the specifics of running a modular input
 
-        :param args: list of command line arguments passed to this script
-        :param event_writer: an EventWriter object for writing events
-        :param input_stream: an input stream for reading inputs
-        :return: an integer to be used as the exit value of this program
+        :param args: List of command line arguments passed to this script.
+        :param event_writer: An ``EventWriter`` object for writing events.
+        :param input_stream: An input stream for reading inputs.
+        :returns: An integer to be used as the exit value of this program.
         """
 
         try:
@@ -101,21 +101,21 @@ def run_script(self, args, event_writer, input_stream):
     def get_scheme(self):
         """The scheme defines the parameters understood by this modular input.
 
-        :return: a Scheme object representing the parameters for this modular input
+        :return: a ``Scheme`` object representing the parameters for this modular input.
         """
 
     def validate_input(self, definition):
         """Handles external validation for modular input kinds. When Splunk
-        called a modular input script in validation mode, it will pass in an XML document
+        calls a modular input script in validation mode, it will pass in an XML document
         giving information about the Splunk instance (so you can call back into it if needed)
         and the name and parameters of the proposed input.
 
         If this function does not throw an exception, the validation is assumed to succeed.
-        Otherwise any error throws will be turned into a string and logged back to Splunk.
+        Otherwise any errors thrown will be turned into a string and logged back to Splunk.
 
         The default implementation always passes.
 
-        :param definition: The parameters for the proposed input passed by splunkd
+        :param definition: The parameters for the proposed input passed by splunkd.
         """
         pass
 
@@ -124,6 +124,6 @@ def stream_events(self, inputs, ew):
         """The method called to stream events into Splunk. It should do all of its output via
         EventWriter rather than assuming that there is a console attached.
 
-        :param inputs: an InputDefinition object
-        :param ew: an object with methods to write events and log messages to Splunk
+        :param inputs: An ``InputDefinition`` object.
+        :param ew: An object with methods to write events and log messages to Splunk.
         """

splunklib/modularinput/script.py

@@ -15,11 +15,11 @@
 # File for utility functions
 
 def xml_compare(expected, found):
-    """Checks equality of two ElementTree objects
+    """Checks equality of two ``ElementTree`` objects.
 
-    :param expected: an ElementTree object
-    :param found: an ElementTree object
-    :return: boolean, equality of expected and found
+    :param expected: An ``ElementTree`` object.
+    :param found: An ``ElementTree`` object.
+    :return: ``Boolean``, whether the two objects are equal.
     """
 
     # if comparing the same ET object

splunklib/modularinput/utils.py

@@ -38,7 +38,7 @@ def __eq__(self, other):
 
     @staticmethod
     def parse(stream):
-        """Creates a ValidationDefinition from a provided stream containing XML.
+        """Creates a ``ValidationDefinition`` from a provided stream containing XML.
 
         The XML typically will look like
 
@@ -57,8 +57,8 @@ def parse(stream):
             </item>
         </items>
 
-        :param stream: stream containing XML to parse
-        :return definition: a ValidationDefinition object
+        :param stream: ``Stream`` containing XML to parse.
+        :return definition: A ``ValidationDefinition`` object.
         """
 
         definition = ValidationDefinition()