[lmi-commits] [lmi] master 06fdee9 2/4: Improve documentation

[Greg Chicares]

branch: master
commit 06fdee902c2ab3012b49ddf49889cad8412e0052
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Improve documentation
---
 multiple_cell_document.cpp | 41 ++++++++++++++++++++++++++++++++++-------
 single_cell_document.cpp   | 21 ++++++++++++++-------
 2 files changed, 48 insertions(+), 14 deletions(-)

diff --git a/multiple_cell_document.cpp b/multiple_cell_document.cpp
index f721add..bd2eb67 100644
--- a/multiple_cell_document.cpp
+++ b/multiple_cell_document.cpp
@@ -40,7 +40,14 @@
 #include <sstream>
 #include <stdexcept>
 
-//============================================================================
+/// Default constructor.
+///
+/// Postconditions: Case, class, and cell parameters all consist of
+/// exactly one default cell.
+///
+/// Calls assert_vector_sizes_are_sane() to assert general invariants
+/// for uniformity, even though it seems impossible for them to be violated.
+
 multiple_cell_document::multiple_cell_document()
     :case_parms_  (1)
     ,class_parms_ (1)
@@ -49,7 +56,14 @@ multiple_cell_document::multiple_cell_document()
     assert_vector_sizes_are_sane();
 }
 
-//============================================================================
+/// Construct from filename.
+///
+/// Postconditions established by parse(): Case, class, and cell
+/// parameters are of sizes {==1, >=1, >=1) respectively.
+///
+/// Calls assert_vector_sizes_are_sane() to assert the postconditions
+/// redundantly, even though they're established by parse().
+
 multiple_cell_document::multiple_cell_document(std::string const& filename)
 {
     xml_lmi::dom_parser parser(filename);
@@ -81,7 +95,8 @@ int multiple_cell_document::class_version() const
     return 2;
 }
 
-//============================================================================
+/// Name of xml root element.
+
 std::string const& multiple_cell_document::xml_root_name() const
 {
     static std::string const s("multiple_cell_document");
@@ -110,6 +125,8 @@ T& hurl(std::string const& s)
 } // Unnamed namespace.
 
 /// Read xml into vectors of class Input.
+///
+/// Calls assert_vector_sizes_are_sane() to assert postconditions.
 
 void multiple_cell_document::parse(xml_lmi::dom_parser const& parser)
 {
@@ -163,6 +180,8 @@ void multiple_cell_document::parse(xml_lmi::dom_parser 
const& parser)
 }
 
 /// Parse obsolete version 0 xml (for backward compatibility).
+///
+/// Calls assert_vector_sizes_are_sane() to assert postconditions.
 
 void multiple_cell_document::parse_v0(xml_lmi::dom_parser const& parser)
 {
@@ -401,7 +420,8 @@ bool 
multiple_cell_document::data_source_is_external(xml::document const& d) con
     return false;
 }
 
-//============================================================================
+/// Coarsely validate file format with XSD schema.
+
 void multiple_cell_document::validate_with_xsd_schema
     (xml::document const& xml
     ,std::string const&   xsd
@@ -433,7 +453,8 @@ xslt::stylesheet& multiple_cell_document::cell_sorter() 
const
     return z;
 }
 
-//============================================================================
+/// Filename of XSD schema for coarsely validating file format.
+
 std::string multiple_cell_document::xsd_schema_name(int version) const
 {
     static std::string const s("multiple_cell_document.xsd");
@@ -451,14 +472,20 @@ std::string multiple_cell_document::xsd_schema_name(int 
version) const
     return oss.str();
 }
 
-//============================================================================
+/// Read from xml file.
+///
+/// Postconditions: established by parse().
+
 void multiple_cell_document::read(std::istream const& is)
 {
     xml_lmi::dom_parser parser(is);
     parse(parser);
 }
 
-//============================================================================
+/// Write to xml file.
+///
+/// Calls assert_vector_sizes_are_sane() to assert preconditions.
+
 void multiple_cell_document::write(std::ostream& os) const
 {
     assert_vector_sizes_are_sane();
diff --git a/single_cell_document.cpp b/single_cell_document.cpp
index 8a3f1c6..3e46b97 100644
--- a/single_cell_document.cpp
+++ b/single_cell_document.cpp
@@ -38,7 +38,8 @@
 #include <ostream>
 #include <sstream>
 
-//============================================================================
+/// Copy constructor.
+
 single_cell_document::single_cell_document(Input const& z)
     :input_data_(z)
 {
@@ -66,14 +67,16 @@ int single_cell_document::class_version() const
     return 2;
 }
 
-//============================================================================
+/// Name of xml root element.
+
 std::string const& single_cell_document::xml_root_name() const
 {
     static std::string const s("single_cell_document");
     return s;
 }
 
-//============================================================================
+/// Read xml into an instance of class Input.
+
 void single_cell_document::parse(xml_lmi::dom_parser const& parser)
 {
     xml::element const& root(parser.root_node(xml_root_name()));
@@ -157,7 +160,8 @@ bool 
single_cell_document::data_source_is_external(xml::document const& d) const
     return false;
 }
 
-//============================================================================
+/// Coarsely validate file format with XSD schema.
+
 void single_cell_document::validate_with_xsd_schema
     (xml::document const& xml
     ,std::string const&   xsd
@@ -189,7 +193,8 @@ xslt::stylesheet& single_cell_document::cell_sorter() const
     return z;
 }
 
-//============================================================================
+/// Filename of XSD schema for coarsely validating file format.
+
 std::string single_cell_document::xsd_schema_name(int version) const
 {
     static std::string const s("single_cell_document.xsd");
@@ -207,14 +212,16 @@ std::string single_cell_document::xsd_schema_name(int 
version) const
     return oss.str();
 }
 
-//============================================================================
+/// Read from xml file.
+
 void single_cell_document::read(std::istream const& is)
 {
     xml_lmi::dom_parser parser(is);
     parse(parser);
 }
 
-//============================================================================
+/// Write to xml file.
+
 void single_cell_document::write(std::ostream& os) const
 {
     xml_lmi::xml_document document(xml_root_name());