fix some more language in the comments
authorDenis Ovsienko <denis@ovsienko.info>
Thu, 5 Jul 2018 17:05:58 +0000 (18:05 +0100)
committerDenis Ovsienko <denis@ovsienko.info>
Thu, 5 Jul 2018 17:06:37 +0000 (18:06 +0100)
[skip ci]

wwwroot/inc/auth.php
wwwroot/inc/code.php
wwwroot/inc/database.php
wwwroot/inc/deviceconfig.php
wwwroot/inc/functions.php
wwwroot/inc/init.php
wwwroot/inc/install.php

index 8223826..4b3bedc 100644 (file)
@@ -12,7 +12,7 @@ be working with only database.php file included.
 
 */
 
-// This function ensures that we don't continue without a legitimate
+// This function ensures that the web-interface does not continue without legitimate
 // username and password (also make sure that both are present, this
 // is especially useful for LDAP auth code to not deceive itself with
 // anonymous binding). It also initializes $remote_* and $*_tags vars.
@@ -540,7 +540,8 @@ function queryLDAPServer ($username, $password)
                foreach ($LDAP_options['options'] as $opt_code => $opt_value)
                        ldap_set_option ($connect, $opt_code, $opt_value);
 
-       // Decide on the username we will actually authenticate for.
+       // Build the server's version of the user's username for ldap_bind(). This may
+       // involve an anonymous (or a non-anonymous, with another ldap_bind()) LDAP search.
        if (isset ($LDAP_options['domain']) && $LDAP_options['domain'] != '')
                $auth_user_name = $username . "@" . $LDAP_options['domain'];
        elseif
index 3717703..bdae1bd 100644 (file)
@@ -321,7 +321,7 @@ class RackCodeParser
                                        'op' => 'clear',
                                        'lineno' => $lineno,
                                );
-                       elseif (! $list) // we need at least one CTXMOD
+                       elseif (! $list) // a CTXMODLIST consists of at least one CTXMOD
                                throw new RCParserError ("expecting CTXMOD");
                        else
                                break;
index 455b64f..b366b25 100644 (file)
@@ -1650,7 +1650,7 @@ function getRackspaceHistory ()
 function getOperationMolecules ($op_id)
 {
        $result = usePreparedSelectBlade ('SELECT old_molecule_id, new_molecule_id FROM MountOperation WHERE id = ?', array ($op_id));
-       // We expect one row.
+       // The result is a single row.
        $row = $result->fetch (PDO::FETCH_ASSOC);
        return array ($row['old_molecule_id'], $row['new_molecule_id']);
 }
@@ -3568,8 +3568,6 @@ function commitDeleteChapter ($chapter_no)
        usePreparedDeleteBlade ('Chapter', array ('id' => $chapter_no, 'sticky' => 'no'));
 }
 
-// This is a dictionary accessor. We perform link rendering, so the user sees
-// nice <select> drop-downs.
 function readChapter ($chapter_id, $style = '')
 {
        $result = usePreparedSelectBlade ('SELECT id FROM Chapter WHERE id = ?', array ($chapter_id));
@@ -3593,7 +3591,8 @@ function readChapter ($chapter_id, $style = '')
                }
                $chapter[$row['dict_key']] = $value;
        }
-       // SQL ORDER BY had no sense, because we need to sort after link rendering, not before.
+       // SQL ORDER BY would make no sense in the query above because the rows need
+       // to be sorted after the wiki link parsing, not before.
        // Try to sort after the parsing in the same way as ORDER BY would do.
        asort ($chapter, SORT_STRING | SORT_FLAG_CASE);
        return $chapter;
@@ -4924,7 +4923,7 @@ function acquireLDAPCache ($username, $max_tries = 2)
        if ($row = fetchLDAPCacheRow ($username, 'FOR UPDATE'))
                return $row;
 
-       // maybe another instance deleted our row before we've locked it. Try again
+       // Maybe another instance deleted the row before this instance had locked it. Try again.
        if ($max_tries > 0)
                return $self ($username, $max_tries - 1);
 
@@ -6049,7 +6048,7 @@ function getDBName()
 }
 
 // Sets exclusive server-global named lock.
-// Always returns TRUE if no exceptions were thrown
+// Returns TRUE or throws an exceptions.
 // A lock is implicitly released on any subsequent call to setDBMutex in the same connection
 function setDBMutex ($name, $timeout = 5)
 {
index 519501d..b72d572 100644 (file)
@@ -878,7 +878,7 @@ function vrp55Read8021QConfig ($input)
                // VRP is known to filter off clauses that don't make sense for
                // current link-type. This way any interface section should contain
                // only one kind of "set native" clause (but if this constraint breaks,
-               // we get a problem).
+               // there is a problem).
                case preg_match ('/^ port (default|trunk pvid) vlan ([[:digit:]]+)$/', $line, $matches):
                        $ret['current']['native'] = $matches[2];
                        break;
@@ -1181,9 +1181,9 @@ function nxos4TranslatePushQueue ($dummy_object_id, $queue, $dummy_vlan_names)
                case 'set mode':
                        if ($cmd['arg2'] == 'trunk')
                        {
-                               // some NX-OS platforms ask for confirmation if user tries to
-                               // overwrite allowed vlan list. Hence, we need to use
-                               // the differentiative remove syntax here
+                               // Some NX-OS platforms interactively ask for a confirmation if the CLI user
+                               // is trying to overwrite the allowed VLAN list for a port. The differentiative
+                               // remove syntax works around this problem.
                                $ret .= "interface ${cmd['arg1']}\n";
                                $ret .= "switchport trunk encapsulation dot1q\n";
                                $ret .= "switchport mode ${cmd['arg2']}\n";
index c7f97bf..ac6fe81 100644 (file)
@@ -613,8 +613,8 @@ function rectHeight ($rackData, $startRow, $template_idx)
                for ($locidx = 0; $locidx < 3; $locidx++)
                {
                        // At least one value in template is TRUE, but the following block
-                       // can meet 'skipped' atoms. Let's ensure we have something after processing
-                       // the first row.
+                       // can meet 'skipped' atoms. Let's ensure there is at least some result
+                       // after processing the first row.
                        if ($template[$template_idx][$locidx])
                        {
                                if
@@ -667,8 +667,8 @@ function markSpan (&$rackData, $startRow, $maxheight, $template_idx)
 }
 
 // This function sets rowspan/solspan/skipped atom attributes for renderRack()
-// What we actually have to do is to find _all_ possible rectangles for each unit
-// and then select the widest of those with the maximal square.
+// by finding _all_ possible rectangles for each rack unit and then selecting
+// the widest of those with the maximal square.
 function markAllSpans (&$rackData)
 {
        for ($i = $rackData['height']; $i > 0; $i--)
@@ -696,7 +696,7 @@ function markBestSpan (&$rackData, $i)
        return TRUE;
 }
 
-// We can mount 'F' atoms and unmount our own 'T' atoms.
+// OK to mount to 'F' atoms and unmount from the current object's 'T' atoms.
 function applyObjectMountMask (&$rackData, $object_id)
 {
        for ($unit_no = $rackData['height']; $unit_no > 0; $unit_no--)
@@ -791,10 +791,9 @@ function markupAtomGrid (&$data, $checked_state)
                }
 }
 
-// This function is almost a clone of processGridForm(), but doesn't save anything to database
-// Return value is the changed rack data.
-// Here we assume that correct filter has already been applied, so we just
-// set or unset checkbox inputs w/o changing atom state.
+// This function is almost a clone of processGridForm(), except it does not modify
+// the database. This code assumes that a correct filter has already been applied,
+// hence it just sets or unsets checkbox inputs and leaves the atom state intact.
 function mergeGridFormToRack (&$rackData)
 {
        $rack_id = $rackData['id'];
@@ -1649,7 +1648,7 @@ function getImplicitTags ($oldtags)
        $tmp = array();
        foreach ($oldtags as $taginfo)
                $tmp = array_merge ($tmp, $taglist[$taginfo['id']]['trace']);
-       // don't call array_unique here, it is in the function we will call now
+       // The call below already includes a call to array_unique().
        return buildTagChainFromIds ($tmp);
 }
 
@@ -1750,7 +1749,7 @@ function redirectIfNecessary ()
        // store the last visited tab name
        if (isset ($_REQUEST['tab']))
                $_SESSION['RTLT'][$pageno] = array ('tabname' => $tabno, 'time' => time());
-       session_commit(); // if we are continuing to run, unlock session data
+       session_commit(); // There was no redirection, unlock the session data.
 }
 
 function prepareNavigation()
@@ -1774,9 +1773,9 @@ function fixContext ($target = NULL)
        if ($target !== NULL)
        {
                $target_given_tags = $target['etags'];
-               // Don't reset autochain, because auth procedures could push stuff there in.
-               // Another important point is to ignore 'user' realm, so we don't infuse effective
-               // context with autotags of the displayed account.
+               // Do not reset the autochain as it may have items generated during the authentication step.
+               // Ignore the "user" realm to keep the displayed user account autotags out of the
+               // effective security context.
                if ($target['realm'] != 'user')
                        $auto_tags = array_merge ($auto_tags, $target['atags']);
        }
@@ -2010,7 +2009,8 @@ function getCellFilter ()
        global $pageno;
        $andor_used = FALSE;
        startSession();
-       // if the page is submitted we get an andor value so we know they are trying to start a new filter or clearing the existing one.
+       // On the form submit "andor" appears on the request and means the user is
+       // trying to start a new filter or clear the existing one.
        if (isset($_REQUEST['andor']))
                $andor_used = TRUE;
        if ($andor_used || array_key_exists ('clear-cf', $_REQUEST))
@@ -3177,9 +3177,9 @@ function buildPredicateTable (&$rackCode)
        // make permitted() calls faster.
        $rackCode = $new_rackCode;
 
-       // Now we have predicate table filled in with the latest definitions of each
-       // particular predicate met. This isn't as chik, as on-the-fly predicate
-       // overloading during allow/deny scan, but quite sufficient for this task.
+       // The latest (and the only, as the interpreter must not allow to redefine predicates)
+       // definition of every predicate is now in the predicate table, which will remain
+       // intact until the end of run-time.
        return $ret;
 }
 
@@ -3857,12 +3857,13 @@ function generate8021QDeployOps ($vswitch, $device_vlanlist, $before, $changes)
        // 2. all "current" non-alien allowed VLANs of those ports that are left
        //    intact (regardless if a VLAN exists in VLAN domain, but looking,
        //    if it is present in device's own VLAN table)
-       // 3. all "new" allowed VLANs of those ports that we do "push" now
+       // 3. all "new" allowed VLANs of the ports to be "pushed" now
        // Like for old_managed_vlans, a VLANs is never listed, only if it
        // exists and belongs to "alien" type.
        $new_managed_vlans = array();
-       // We need to count down the number of ports still using specific vlan
-       // in order to delete it from device as soon as vlan will be removed from the last port
+       // It is necessary to count down the number of ports still using a specific VLAN
+       // in order to unconfigure the VLAN on the switch as soon as the VLAN membership
+       // is removed from its last port.
        // This array tracks port count:
        //  * keys are vlan_id's;
        //  * values are the number of changed ports that were using this vlan in old configuration
@@ -6115,7 +6116,7 @@ function registerHook ($hook_name, $callback, $method = 'after')
                array_push ($hooks_stack[$hook_name], $hook[$hook_name]);
        $hook[$hook_name] = 'universalHookHandler';
 
-       // if we are trying to register on the built-in function, push it to the stack
+       // If the hook name is a built-in function, the function needs to be the first on the stack.
        if (empty ($hooks_stack[$hook_name]) && is_callable ($hook_name))
                array_push ($hooks_stack[$hook_name], $hook_name);
 
index 603bcca..2063ff5 100644 (file)
@@ -122,8 +122,8 @@ if (! isset ($script_mode) || $script_mode !== TRUE)
        // even given/implicit tags. It also sets remote_username and remote_displayname.
        authenticate();
        // Authentication passed.
-       // Note that we don't perform autorization here, so each 1st level page
-       // has to do it in its way, e.g. by calling authorize() after fixContext().
+       // Note that authorization does not happen here as every CLI script, HTTP module and
+       // page does it differently, e.g. by calling authorize() after fixContext().
 }
 elseif (! isset ($remote_username))
 {
index 4ff2a89..fcd2314 100644 (file)
@@ -90,11 +90,11 @@ function not_already_installed()
        }
 }
 
-// Check that we can write to configuration file.
-// If so, ask for DB connection paramaters and test
-// the connection. Neither save the parameters nor allow
-// going further until we succeed with the given
-// credentials.
+// Test that the web-server can write to the configuration file.
+// If so, prompt for the DB connection parameters and test
+// the connection. Do not save the parameters into the configuration
+// file until the database connection succeeds. Do not proceed to the
+// next steps until a working configuration file is in place.
 function init_config ()
 {
        function print_form