[lmi-commits] [lmi] master f387d77 1/3: Comment standalone functions where they are implemented

[Greg Chicares]

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

    Comment standalone functions where they are implemented
    
    Moved comments from header to implementation. Insertions outnumber
    deletions only because one comment had been duplicated in both files.
---
 miscellany.cpp | 23 +++++++++++++++++++++++
 miscellany.hpp | 25 -------------------------
 2 files changed, 23 insertions(+), 25 deletions(-)

diff --git a/miscellany.cpp b/miscellany.cpp
index 2ea4baf..a0825af 100644
--- a/miscellany.cpp
+++ b/miscellany.cpp
@@ -58,6 +58,8 @@ bool streams_are_identical(std::istream& is0, std::istream& 
is1)
 }
 } // Unnamed namespace.
 
+/// Test whether two files are identical. Arguments are filenames.
+
 bool files_are_identical(std::string const& file0, std::string const& file1)
 {
     std::ifstream ifs0(file0.c_str(), ios_in_binary());
@@ -67,11 +69,15 @@ bool files_are_identical(std::string const& file0, 
std::string const& file1)
     return streams_are_identical(ifs0, ifs1);
 }
 
+/// Return the number of newline characters in a string.
+
 std::size_t count_newlines(std::string const& s)
 {
     return std::count(s.begin(), s.end(), '\n');
 }
 
+/// Split an internally-newline-delimited string into lines.
+
 std::vector<std::string> split_into_lines(std::string const& s)
 {
     // BOOST !! Unfortunately boost::split() can't be easily used with the
@@ -123,6 +129,8 @@ std::string htmlize(std::string const& raw_text)
     return html;
 }
 
+/// Ascertain whether string begins with prefix.
+
 bool begins_with(std::string const& s, std::string const& prefix)
 {
     return
@@ -130,6 +138,8 @@ bool begins_with(std::string const& s, std::string const& 
prefix)
         && std::equal(prefix.begin(), prefix.end(), s.begin());
 }
 
+/// Ascertain whether string ends with suffix.
+
 bool ends_with(std::string const& s, std::string const& suffix)
 {
     return
@@ -137,6 +147,8 @@ bool ends_with(std::string const& s, std::string const& 
suffix)
         && std::equal(suffix.rbegin(), suffix.rend(), s.rbegin());
 }
 
+/// Remove superfluous characters from beginning of string.
+
 void ltrim(std::string& s, char const* superfluous)
 {
     std::string::size_type p = s.find_first_not_of(superfluous);
@@ -150,6 +162,8 @@ void ltrim(std::string& s, char const* superfluous)
         }
 }
 
+/// Remove superfluous characters from end of string.
+
 void rtrim(std::string& s, char const* superfluous)
 {
     std::string::size_type p = s.find_last_not_of(superfluous);
@@ -163,6 +177,8 @@ void rtrim(std::string& s, char const* superfluous)
         }
 }
 
+/// Omitting colons yields a valid posix path.
+///
 /// 
http://groups.google.com/group/borland.public.cpp.borlandcpp/msg/638d1f25e66472d9
 ///   [2001-07-18T22:25:15Z from Greg Chicares]
 
@@ -178,6 +194,8 @@ std::string iso_8601_datestamp_verbose()
     return s;
 }
 
+/// Colons separate HH:MM:SS, so result is not a valid posix path.
+
 std::string iso_8601_datestamp_terse()
 {
     std::size_t const len = sizeof "CCYYMMDDTHHMMSSZ";
@@ -190,6 +208,11 @@ std::string iso_8601_datestamp_terse()
     return s;
 }
 
+/// Compute the number of pages needed to display the given number of non-blank
+/// rows in groups of the specified size separated by blank rows.
+///
+/// Preconditions: 0 < total_rows && 0 < rows_per_group <= rows_per_page
+
 int page_count
     (int total_rows
     ,int rows_per_group
diff --git a/miscellany.hpp b/miscellany.hpp
index bf8b99a..170b497 100644
--- a/miscellany.hpp
+++ b/miscellany.hpp
@@ -61,8 +61,6 @@ bool each_equal(RangeExpression const& range, T const& t)
     return true;
 }
 
-/// Test whether two files are identical. Arguments are filenames.
-
 bool files_are_identical(std::string const&, std::string const&);
 
 /// Ascertain vector minimum and maximum efficiently.
@@ -95,32 +93,18 @@ template<typename T> bool operator<=(T t, minmax<T> m) 
{return t <= m.minimum();
 template<typename T> bool operator< (minmax<T> m, T t) {return m.maximum() <  
t;}
 template<typename T> bool operator<=(minmax<T> m, T t) {return m.maximum() <= 
t;}
 
-/// Return the number of newline characters in a string.
-
 std::size_t LMI_SO count_newlines(std::string const&);
 
-/// Split an internally-newline-delimited string into lines.
-
 std::vector<std::string> LMI_SO split_into_lines(std::string const&);
 
-/// Escape text for html, e.g., "a < b" --> "a &lt; b".
-
 std::string htmlize(std::string const&);
 
-/// Ascertain whether string begins with prefix.
-
 bool LMI_SO begins_with(std::string const& s, std::string const& prefix);
 
-/// Ascertain whether string ends with suffix.
-
 bool LMI_SO ends_with(std::string const& s, std::string const& suffix);
 
-/// Remove superfluous characters from beginning of string.
-
 void LMI_SO ltrim(std::string& s, char const* superfluous);
 
-/// Remove superfluous characters from end of string.
-
 void LMI_SO rtrim(std::string& s, char const* superfluous);
 
 inline std::ios_base::openmode ios_in_binary()
@@ -156,12 +140,8 @@ inline std::ios::fmtflags 
set_default_format_flags(std::ios_base& stream)
     return stream.setf(std::ios::skipws | std::ios::dec);
 }
 
-/// Omitting colons yields a valid posix path.
-
 std::string iso_8601_datestamp_terse();
 
-/// Colons separate HH:MM:SS, so result is not a valid posix path.
-
 std::string iso_8601_datestamp_verbose();
 
 template<typename T, std::size_t n>
@@ -189,11 +169,6 @@ inline unsigned char lmi_toupper(unsigned char c)
     return static_cast<unsigned char>(std::toupper(c));
 }
 
-/// Compute the number of pages needed to display the given number of non-blank
-/// rows in groups of the specified size separated by blank rows.
-///
-/// Preconditions: 0 < total_rows && 0 < rows_per_group <= rows_per_page
-
 int LMI_SO page_count
     (int total_rows
     ,int rows_per_group