Merge pull request #272 from mvidner/doc-mode

Document the Mode library

library/general/src/modules/Mode.rb

@@ -35,6 +35,56 @@
 require "yast"
 
 module Yast
+  # There are three modes combined here:
+  #
+  # 1. Installation
+  # 2. UI
+  # 3. Test
+  #
+  # See the boolean methods linked in the below tables for the *meaning*
+  # of the modes.
+  #
+  # A related concept is the installation {StageClass Stage}.
+  #
+  # # *Installation* mode
+  #
+  # It is the most complex one. Its values are used in the installation
+  # {https://github.com/yast/?query=skelcd-control control files}.
+  #
+  # It has these mutually exclusive values and corresponding boolean queries:
+  # <table>
+  # <tr><th> {#mode} value </th>    <th colspan=2> boolean shortcut   </th></tr>
+  # <tr><td> normal </td>           <td colspan=2> {#normal}          </td></tr>
+  # <tr><td> installation </td>     <td rowspan=3> {#installation}    </td></tr>
+  # <tr><td> autoinstallation </td> <td>         {#autoinst} (short!) </td></tr>
+  # <tr><td> live_installation </td><td>         {#live_installation} </td></tr>
+  # <tr><td> autoinst_config </td>  <td colspan=2> {#config}          </td></tr>
+  # <tr><td> update </td>           <td rowspan=2> {#update}          </td></tr>
+  # <tr><td> autoupgrade </td>      <td>           {#autoupgrade}     </td></tr>
+  # <tr><td> repair (obsolete) </td><td colspan=2> {#repair}          </td></tr>
+  # </table>
+  #
+  # # *UI* mode
+  #
+  # It has these mutually exclusive values and corresponding boolean queries:
+  # <table>
+  # <tr><th> {#ui} value</th>   <th> boolean shortcut </th></tr>
+  # <tr><td> dialog       </td> <td> (none)           </td></tr>
+  # <tr><td> commandline  </td> <td> {#commandline}   </td></tr>
+  # <tr><td> none(*)      </td> <td> (none)           </td></tr>
+  # </table>
+  #
+  # Apparently "none" is never used.
+  #
+  # # *Test* mode
+  #
+  # It has these mutually exclusive values and corresponding boolean queries:
+  # <table>
+  # <tr><th> {#testMode} value</th>  <th colspan=2> boolean shortcut </th> </tr>
+  # <tr><td> test </td>              <td rowspan=3> {#test} </td></tr>
+  # <tr><td> testsuite  </td>        <td> {#testsuite}      </td></tr>
+  # <tr><td> screenshot (obsolete)</td><td> {#screen_shot}  </td></tr>
+  # </table>
   class ModeClass < Module
     def main
 
@@ -53,7 +103,9 @@ def main
       @_ui = "dialog"
     end
 
-    # initialize everything from command-line of y2base
+    # Initialize everything from command-line of y2base.
+    #
+    # @note {#ui} aka {#commandline} is not initialized. Probably a bug.
     def Initialize
       @_mode = "normal"
       @_test = "none"
@@ -109,6 +161,7 @@ def mode
       @_mode
     end
 
+    # Setter for {#mode}.
     def SetMode(new_mode)
       Initialize() if @_mode == nil
 
@@ -150,6 +203,7 @@ def testMode
       @_test
     end
 
+    # Setter for {#testMode}
     def SetTest(new_test_mode)
       Initialize() if @_test == nil
 
@@ -172,6 +226,7 @@ def ui
       @_ui
     end
 
+    # Setter for {#ui}.
     def SetUI(new_ui)
       if !Builtins.contains(["commandline", "dialog", "none"], new_ui)
         Builtins.y2error("Unknown UI mode %1", new_ui)
@@ -183,73 +238,90 @@ def SetUI(new_ui)
 
     # main mode wrappers
 
-    # we're doing a fresh installation
+    # We're doing a fresh installation, not an {#update}.
+    # Also true for the firstboot stage.
     def installation
       mode == "installation" || mode == "autoinstallation" ||
         mode == "live_installation"
     end
 
-    # we're doing a fresh installation from live CD/DVD
+    # We're doing a fresh installation from live CD/DVD.
+    # {#installation} is also true.
     def live_installation
       mode == "live_installation"
     end
 
-    # we're doing an update
+    # We're doing a distribution upgrade (wrongly called an "update").
     def update
       mode == "update" || mode == "autoupgrade"
     end
 
+    # Depeche Mode. If you are a Heavy Metal fan, too bad!
     def Depeche
       true
     end
 
-    # normal, running system
+    # The default installation mode. That is, no installation is taking place.
+    # We are configuring a system whose installation has concluded.
     def normal
       mode == "normal"
     end
 
-    # start repair module
+    # Repair mode. Probably obsolete since the feature was dropped.
     def repair
       mode == "repair"
     end
 
-    # doing auto-installation
+    # Doing auto-installation with AutoYaST.
+    # This is different from the {#config} part of AY.
+    # {#installation} is also true.
     def autoinst
       mode == "autoinstallation"
     end
 
-    # doing auto-upgrade
+    # Doing auto-upgrade. {#update} is also true.
+    # {#autoinst} is false even though AY is running,
+    # which is consistent with {#installation} being exclusive with {#update}.
     def autoupgrade
       mode == "autoupgrade"
     end
 
-    # configuration for auto-installation, only in running system
+    # Configuration for {#autoinst}, usually in the running system.
+    #
+    # @note also true during the installation
+    #  when cloning the just installed system.
     def config
       mode == "autoinst_config"
     end
 
     # test mode wrappers
 
-    # Just testing.
-    # See installation/Test-Scripts/doit*
+    # Synonym of {#testsuite}.
+    # (Formerly (2006) this was a different thing, an obsolete "dry-run"
+    # AKA "demo" mode. But the current usage means "{#testsuite}")
     def test
       testMode == "test" || testMode == "screenshot" || testMode == "testsuite"
     end
 
-    # dump screens to /tmp. Implies {#demo} .
-    # See installation/Test-Scripts/yast2-screen-shots*
+    # Formerly used to help take screenshots for the manuals.
+    # Obsolete since 2006.
     def screen_shot
       testMode == "screenshot"
     end
 
     # Returns whether running in testsuite.
+    # Set by legacy test framework yast2-testsuite, used to work around
+    # non existent stubbing. Avoid!
     def testsuite
       testMode == "testsuite"
     end
 
     # UI mode wrappers
 
-    # we're running in command line interface
+    # We're running in command line interface, not in GUI or ncurses TUI.
+    #
+    # @note this is set in the {CommandLineClass CommandLine} library,
+    #  not in the core, and defaults to false.
     # @return true if command-line is running
     def commandline
       ui == "commandline"