[lmi-commits] [lmi] master 43d57bf 1/6: Consolidate and improve commentary

[Greg Chicares]

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

    Consolidate and improve commentary
---
 wx_table_generator.cpp | 53 ++++++++++++++++++--------------------------------
 1 file changed, 19 insertions(+), 34 deletions(-)

diff --git a/wx_table_generator.cpp b/wx_table_generator.cpp
index 83ff21d..f7c7cc4 100644
--- a/wx_table_generator.cpp
+++ b/wx_table_generator.cpp
@@ -322,27 +322,26 @@ wxRect wx_table_generator::text_rect(std::size_t column, 
int y)
 
 // class members used, mutably or immutably:
 //
-// const    total_width_
-// mutable  column_margin_
-// mutable  all_columns_
-//   i.e. std::vector<column_info> all_columns_;
-// mutable  column_info elements
-//   the only column_info function member called is is_hidden()
-//   the only column_info data member modified is col_width_
+// const    total_width_    max table width (page width - page margins)
+// mutable  column_margin_  spacing on both left and right of column
+// mutable  all_columns_    std::vector<column_info>
+//   column_info::col_width_ is the only member changed
 //
-// meanings (written before each variable, as in header documentation):
-//
-    // ctor parameter:
-    // max table width (page width minus horizontal page margins)
-// const    total_width_
-    // spacing on both left and right of column
-    // initialized in ctor to # pixels in one em: (dc_.GetTextExtent("M").x)
-    // changed in this function and nowhere else
-// mutable  column_margin_
-    // std::vector<column_info>
-// mutable  all_columns_
+// column_margin_ and col_width_ are modified here and nowhere else
 
 /// Compute column widths.
+///
+/// First, allocate adequate width to each inelastic column; then
+/// distribute any excess width left over among elastic columns.
+///
+/// The width of each inelastic column reflects:
+///  - a mask like "999,999" (ideally, there would instead be a
+///    quasi-global data structure mapping symbolic column names
+///    to their corresponding headers and maximal widths)
+///  - the header width
+///  - the bilateral margins that have already been added
+/// The margins may be slightly reduced by this function to make
+/// everything fit when it otherwise wouldn't.
 
 void wx_table_generator::compute_column_widths()
 {
@@ -350,25 +349,9 @@ void wx_table_generator::compute_column_widths()
     int number_of_columns = 0;
 
     // Number of non-hidden elastic columns.
-    //
-    // In practice, only the "Participant" column on group quotes has
-    // this property.
-    //
-    // The rationale for this property is that, once adequate width
-    // has been allocated to each column, any excess width left over
-    // is to be distributed among such elastic columns only:
-    // i.e., they (and only they) are to be "expanded".
     int number_of_elastic_columns = 0;
 
     // Total width of all non-hidden inelastic columns.
-    // The width of each inelastic column reflects:
-    //  - a mask like "999,999" (ideally, there would instead be a
-    //    quasi-global data structure mapping symbolic column names
-    //    to their corresponding headers and maximal widths)
-    //  - the header width
-    //  - the bilateral margins that have already been added
-    // The margins may be slightly reduced by this function to make
-    // everything fit when it otherwise wouldn't.
     int total_inelastic_width = 0;
 
     for(auto const& i : all_columns())
@@ -427,6 +410,8 @@ void wx_table_generator::compute_column_widths()
 // is less than the padding.
 //
 // Is this as good as it can be, given that coordinates are integers?
+// Answer: Yes--the integers count points, not ems or characters, and
+// typographers wouldn't use any finer unit for this task.
             if(overflow_per_column <= 2 * column_margin())
                 {
                 // We are going to reduce the total width by more than