updates for online documentation

src/Coyote.py

@@ -1,9 +1,10 @@
 #Create a plot and save to .png
+#Note: An important detail to keep in mind is that you need to call 
+# showPlot() early on. Scripting emulates what you would do interactively;
+# it is not a "command driven" procedure. You cannot change features on 
+# a plot until they exist and the showPlot() function causes the plot 
+# object to come into existence.
 from hec.script import Plot, MessageBox, AxisMarker
-# from hec.io import TimeSeriesContainer
-# from hec.io import PairedDataContainer
-# from hec.hecmath import TimeSeriesMath
-# from hec.hecmath import PairedDataMath
 from hec.heclib.dss import HecDss, DSSPathname
 import java
 from hec.script.Constants import TRUE, FALSE

src/Folsom.py

@@ -1,9 +1,11 @@
 #Create and Diplay a plot
+# This example shows a more complex plot where we break the rule of 
+# showPlot() of creating the plot prior to changing it. 
+# In this case, configurePlotLayout() will also create the plot. 
+# In this plot of Folsom Lake, we create three separate viewports 
+# and size them according to the different data types.
 from hec.script import Plot, MessageBox
-# from hec.io import TimeSeriesContainer
-# from hec.io import PairedDataContainer
-# from hec.hecmath import TimeSeriesMath
-# from hec.hecmath import PairedDataMath
+
 from hec.heclib.dss import HecDss
 import java
 from hec.script.Constants import TRUE, FALSE

src/FolsomTable.py

@@ -1,10 +1,10 @@
 #Create and display a table
+#Creating a table from a script is easier than plots as 
+# there is less to do. Like plots, you retrieve the data, 
+# add the data to a Vector, create a table and set the data, 
+# and then show the table.
 from hec.script import Plot, MessageBox
 from hec.dataTable import HecDataTableFrame
-# from hec.io import TimeSeriesContainer
-# from hec.io import PairedDataContainer
-# from hec.hecmath import TimeSeriesMath
-# from hec.hecmath import PairedDataMath
 from hec.heclib.dss import HecDss
 import java
 import sys

src/GagePlot.py

@@ -1,5 +1,13 @@
-#Run a script with arguments for "location" and "version"
+#The GagePlot script is designed to produce a standard plot for a gage
+# where there is both a stream flow gage and a precipitation gage.
+
 # this script is run by passing arguments from RunGages.py
+# To access arguments passed into the script you must include the following:
+# import sys (sm = globals())
+# Arguments are passed into a python script using a "name-space dictionary", which gives the keyword followed by a colon and then the parameter. Inside the script, the keyword will be replaced with the parameter. For example, in the GagePlot script, the name-space dictionary could be:
+# "location" : "Glenfir", "version" : "OBS"
+# Wherever the string location or version is in the script will
+#  be substituted with GlenFir and Obs, respectively. 
 
 from hec.script import Plot, MessageBox
 from hec.heclib.dss import HecDss, DSSPathname

src/OakvilleSimple.py

@@ -1,4 +1,16 @@
 # Simple Plotting Example
+# Generally, graphics scripts may be broken into five segments; 
+# 1) Retrieve the data; 
+# 2) Initialize the plot; 
+# 3) Bring the plot into existence with showPlot(); 
+# 4) Change the plot; and 
+# 5) Save the plot to file and close.
+# Most people are tripped up with the function showPlot(). 
+# This function puts all the parts together and creates the plot. 
+# One would think that this would be called at the end of the script, 
+# but to the contrary, it needs to be called near the beginning.
+# For example, you can not change or set a curve's color until the curve exists, and the showPlot() function is what creates curves. Scripting is emulating the steps that you would do interactively; it is not a command language.
+# HecDss uses exceptions for error processing, such as indicating missing data. You need to use try: except loops to catch errors, otherwise an exception message will be written to the output and that exception may not be very clear.
 from hec.script import Plot, MessageBox
 from hec.heclib.dss import HecDss, DSSPathname
 import java