Fix some LaTeX code comments [ci skip]

sphinx/texinputs/sphinxlatextables.sty

@@ -30,15 +30,16 @@
 % - \sphinxtoprule
 % - \sphinxmidrule
 % - \sphinxbottomrule
-% - \sphinxarrayrulewidth
+% - \sphinxtableatstartofbodyhook
+% - \sphinxtableafterendhook
 % - \sphinxthistablewithglobalstyle
 % - \sphinxthistablewithbooktabsstyle
 % - \sphinxthistablewithborderlessstyle
 % - \sphinxthistablewithstandardstyle
 % - \sphinxthistablewithcolorrowsstyle
 % - \sphinxthistablewithnocolorrowsstyle
-% - \sphinxtableatstartofbodyhook
-% - \sphinxtableafterendhook
+% - \sphinxthistablewithvlinesstyle
+% - \sphinxthistablewithnovlinesstyle
 %
 % Executes \RequirePackage for:
 %
@@ -419,8 +420,7 @@
 % - prior to <5.2.0, Sphinx did not officially support colour in tables,
 %   but it did have a mechanism to protect merged cells from being partly
 %   covered by colour panels at various places.  At 5.2.0 this mechanism
-%   is relaxed a bit to allow row colour for a single-row merged cell
-%   which is mostly useful for a cell taking all table width I guess.
+%   is relaxed a bit to allow row colour for a single-row merged cell.
 %
 % \spx@table@hackCT@inmergedcell
 % \spx@table@hackCT@nocolor
@@ -739,13 +739,7 @@
 %   ... or not if there are two \cline's in the row...
 %   (as we will use same mechanism we have to correct this increment).
 %
-% So we need our own code.  And matters of longtable unfortunately force
-% us to some addition to table template, simply hooking into in-place
-% \sphinxtoprule etc mark-up is not enough.  After some hesitation and due
-% to problems of the continuation hints of longtable we decide not to try
-% for coloured headers (which would be fine with tabular and tabulary
-% actually) except for the first header row via a \rowcolor, not via the
-% \rowcolors-style hack into \CT@everycr.
+% So we need our own code.
 
 % Provide \rownum and rownum LaTeX counter (code copied from colortbl v1.0f)
 \ltx@ifundefined{rownum}{%
@@ -825,7 +819,7 @@
           % table, we must reset explicitly the \everycr here.  But
           % we don't use the colortbl default value of \CT@everycr, as it
           % resets \CT@row@color to \relax but we want the next header rows
-          % to obey same color scheme
+          % to obey same color scheme as the first one.
           \global\CT@everycr{\the\everycr}%
 % if we could require xcolor we could make it nice colour scheme with each new
 % header row at 90% of previous row colour, for example.
@@ -930,13 +924,9 @@ to allow local use of booktabs table style}%
 
 % colorrows style
 %
-% this is defined to be executed only once (if both latex_book_style contains
-% 'colorrows' and the table receives the class colorrows, this means the macro
-% is executed twice, but it prepends hooks and one of them decrements \rownum so
-% should be prepended only once).  The self-annihilation is done in a scope
-% limiting environment.
+% this is defined to auto-silence itself (in the surrounding scope-limiting
+% environment) after one execution
 \def\sphinxthistablewithcolorrowsstyle{%
-% only do its job once
     \let\sphinxthistablewithcolorrowsstyle\@empty
 %
     \let\spx@table@toprulehook         \spx@table@@toprulehook
@@ -945,7 +935,7 @@ to allow local use of booktabs table style}%
     \spx@prepend\spx@table@toprulehook       \to\sphinxtabletoprulehook
     \spx@prepend\spx@table@startbodycolorrows\to\sphinxtableatstartofbodyhook
 %
-% this one is not set to \@empty by norowcolors, because it looks harmless
+% this one is not set to \@empty by nocolorrows, because it looks harmless
 % to execute it always, as it simply resets to standard colortbl state after
 % the table; so we don't need an @@ version for this one
     \spx@prepend\spx@table@resetcolortbl\to\sphinxtableafterendhook
@@ -957,21 +947,21 @@ to allow local use of booktabs table style}%
 }%
 
 \def\sphinxthistablewithnocolorrowsstyle{%
-% rather than trying to remove the code added by 'rowcolors' style, we 
+% rather than trying to remove the code added by 'colorrows' style, we 
 % simply make it no-op, without even checking if really it was activated.
     \let\spx@table@toprulehook       \@empty
     \let\spx@table@startbodycolorrows\@empty
     \let\sphinxtabledecrementrownum  \@empty
 % we don't worry about \sphinxtableafterendhook as the \spx@table@resetcolortbl
-% done at end can not do harm; and also we could have not bothered with the
+% done at end can not do harm; and also we could also have not bothered with the
 % \sphinxtabledecrementrownum as its \rownum decrement, if active, is harmless
 % in non-colorrows context
 }
 
 % The \sphinxarrayrulewidth is used for some complex matters of merged
 % cells size computations
-% tabularcolumns argument will override any global or local style
-% regarding the presence or not of vertical separator.
+% tabularcolumns argument will override any global or local style and
+% trigger the appropriate adjustement of \sphinxarrayrulewidth
 \def\sphinxthistablewithvlinesstyle{%
     \def\sphinxarrayrulewidth{\arrayrulewidth}%
 }%
@@ -991,6 +981,7 @@ to allow local use of booktabs table style}%
 \ifspx@opt@borderless
     \def\sphinxthistablewithglobalstyle{\sphinxthistablewithborderlessstyle}
 \fi
+% colorrows appends to the current globalstyle (standard, booktabs, or borderless)
 \ifspx@opt@colorrows % let the globalstyle trigger the colorrows style on top of it
     \expandafter\def\expandafter\sphinxthistablewithglobalstyle\expandafter
     {\sphinxthistablewithglobalstyle