fix some language in comments
authorDenis Ovsienko <denis@ovsienko.info>
Tue, 3 Jul 2018 13:05:56 +0000 (14:05 +0100)
committerDenis Ovsienko <denis@ovsienko.info>
Tue, 3 Jul 2018 13:08:34 +0000 (14:08 +0100)
"We" isn't a good word for making comments on a technical subject.
Remove some obsolete comments altogether.

[skip ci]

wwwroot/inc/interface.php
wwwroot/inc/ophandlers.php
wwwroot/inc/remote.php
wwwroot/inc/snmp.php
wwwroot/inc/triggers.php
wwwroot/inc/upgrade.php

index 9089b74..07bb62f 100644 (file)
@@ -2143,13 +2143,8 @@ function renderPortsInfo($object_id)
        echo "</td></tr></table>";
 }
 
-/*
-The following conditions must be met:
-1. We can mount onto free atoms only. This means: if any record for an atom
-already exists in RackSpace, it can't be used for mounting.
-2. We can't unmount from 'W' atoms. Operator should review appropriate comments
-and either delete them before unmounting or refuse to unmount the object.
-*/
+// An object can be mounted onto free atoms only, that is, if any record for an atom
+// already exists in RackSpace, it cannot be used for mounting.
 function renderRackSpaceForObject ($object_id)
 {
        // Always process occupied racks plus racks chosen by user. First get racks with
@@ -2241,8 +2236,8 @@ function renderRackSpaceForObject ($object_id)
        finishPortlet();
        echo "</td>";
 
-       // Right portlet with rendered racks. If this form submit is not final, we have to
-       // reflect the former state of the grid in current form.
+       // Right portlet with rendered racks. If this form submit is not final,
+       // the former state of the grid needs to make it to the current form.
        echo "<td class=pcright rowspan=2 height='1%'>";
        startPortlet ('Working copy');
        includeJQueryUI (false);
@@ -2255,7 +2250,7 @@ function renderRackSpaceForObject ($object_id)
                // Order is important here: only original allocation is highlighted.
                highlightObject ($rackData, $object_id);
                markupAtomGrid ($rackData, 'T');
-               // If we have a form processed, discard user input and show new database
+               // If an HTTP form has been processed, discard user input and show new database
                // contents.
                if (!$is_ro && isset ($_REQUEST['rackmulti'][0])) // is an update
                        mergeGridFormToRack ($rackData);
@@ -2315,7 +2310,7 @@ function renderMolecule ($mdata, $object_id)
                $rackpack[$rack_id][$unit_no][$loclist[$atom]]['state'] = 'T';
                $rackpack[$rack_id][$unit_no][$loclist[$atom]]['object_id'] = $object_id;
        }
-       // now we have some racks to render
+       // Now there are some racks to render.
        foreach ($rackpack as $rackData)
        {
                markAllSpans ($rackData);
@@ -5321,7 +5316,7 @@ function showPathAndSearch ($pageno, $tabno)
        echo '<input type=hidden name=page value=search>';
        echo "<input type=hidden name=last_page value=$pageno>";
        echo "<input type=hidden name=last_tab value=$tabno>";
-       // This input will be the first, if we don't add ports or addresses.
+       // This input's implicit tabindex will be the lowest unless there is a form with ports or addresses on the page.
        echo '<label><u>S</u>earch:<input accesskey="s" type=text name=q size=20 value="';
        echo array_key_exists ('q', $sic) ? stringForTextInputValue ($sic['q']) : '';
        echo '"></label></form></div>';
index db2f765..3565794 100644 (file)
@@ -1126,14 +1126,14 @@ function processGridForm (&$rackData, $unchecked_state, $checked_state, $object_
                                $dbxlink->rollBack();
                                return FALSE;
                        }
-                       // Here we avoid using ON DUPLICATE KEY UPDATE by first performing DELETE
-                       // anyway and then looking for probable need of INSERT.
+                       // This code uses an unconditional DELETE followed by a conditional INSERT
+                       // rather than ON DUPLICATE KEY UPDATE.
                        usePreparedDeleteBlade ('RackSpace', array ('rack_id' => $rack_id, 'unit_no' => $unit_no, 'atom' => $atom));
                        if ($newstate != 'F')
                                usePreparedInsertBlade ('RackSpace', array ('rack_id' => $rack_id, 'unit_no' => $unit_no, 'atom' => $atom, 'state' => $newstate));
                        if ($newstate == 'T' && $object_id != 0)
                        {
-                               // At this point we already have a record in RackSpace.
+                               // At this point respective row exists in RackSpace and has state set to "T".
                                usePreparedUpdateBlade
                                (
                                        'RackSpace',
@@ -3422,7 +3422,7 @@ function deleteVlan()
        $n_cleared = pinpointDeleteVlan ($vdom_id, $vlan_id);
        if ($n_cleared > 0)
                showSuccess ("VLAN $vlan_id removed from $n_cleared port(s)");
-       // since there is no strict foreign keys refering VLANDescription, we can delete a row
+       // Since there are no strict foreign keys refering VLANDescription, it is safe just to delete the row.
        usePreparedDeleteBlade ('VLANDescription', array ('domain_id' => $vdom_id, 'vlan_id' => $vlan_id));
        showSuccess ("VLAN $vlan_id has been deleted");
        return buildRedirectURL ('vlandomain', 'default', array ('vdom_id' => $vdom_id));
index df09f75..d74b79c 100644 (file)
@@ -468,7 +468,7 @@ function queryTerminal ($object_id, $commands, $tolerate_remote_errors = TRUE)
                        $protocol = 'netcat'; // default is netcat mode
                        $prompt = '^(Login|Username|Password|Please Enter Password): $|^\S+[>#]$'; // set the prompt in case user would like to specify telnet protocol
                        $commands = "skip-page-display\n" . $commands;
-                       # using ssh and sshnokey we'll always receive 'Connection to $ip closed by remote host.' upon exit
+                       # Using ssh and sshnokey will always result in 'Connection to $ip closed by remote host.' upon exit.
                        # let's hide the warnings
                        $tolerate_remote_errors = TRUE;
                        $hide_warnings = TRUE;
@@ -678,7 +678,7 @@ function callScript ($gwname, $params, $in, &$out, &$errors)
                        $gateway_log = substr ($gateway_log, -MAX_GW_LOGSIZE);
 
        }
-       // we need to destroy our global link to the resource here.
+       // The global link to the resource needs to be destroyed here.
        // PHP's proc_close implementation does nothing itself: it only returns
        // the value saved by the resource destructor. If the resource was not
        // destroyed (refcnt > 0), the return value is incorrect.
@@ -733,7 +733,7 @@ function setDevice8021QConfig ($object_id, $pseudocode, $vlan_names)
 // (i.e. some function in deviceconfig.php)
 function shortenIfName ($if_name, $breed = NULL, $object_id = NULL)
 {
-       // this is a port name we invented in snmp.php, do not translate it
+       // This is a port name invented in snmp.php, do not translate it.
        if (preg_match ('/^AC-in(-[12])?$/', $if_name))
                return $if_name;
 
index 0478c7c..21a4609 100644 (file)
@@ -4614,7 +4614,7 @@ function doSwitchSNMPmining ($objectInfo, $device)
                $randomindex = preg_replace ("/^.*ifPhysAddress\.(.+)\$/", '\\1', $oid);
                $value = trim ($value);
                // NET-SNMP may return MAC addresses in one of two (?) formats depending on
-               // DISPLAY-HINT internal database. The best we can do about it is to accept both.
+               // DISPLAY-HINT internal database. Try to work around it.
                // Bug originally reported by Walery Wysotsky against openSUSE 11.0.
                if (preg_match ('/^string: [0-9a-f]{1,2}(:[0-9a-f]{1,2}){5}/i', $value)) // STRING: x:yy:z:xx:y:zz
                {
@@ -4632,7 +4632,8 @@ function doSwitchSNMPmining ($objectInfo, $device)
                        continue; // martian format
                $ifInfo[$randomindex]['ifPhysAddress'] = implode ('', $addrbytes);
        }
-       // process each interface only once regardless of how many processors we have to run
+       // Zero or more (depending on the way they are defined) processors may yield
+       // RackTables ports for each SNMP port.
        foreach ($ifInfo as $iface)
                foreach ($known_switches[$sysObjectID]['processors'] as $processor_name)
                {
index ac94ca4..e086fb7 100644 (file)
@@ -69,9 +69,6 @@ function trigger_liveports ()
        return '';
 }
 
-// SNMP port finder tab trigger. At the moment we decide on showing it
-// for pristine switches/PDUs only. Once a user has begun
-// filling the data in, we stop showing the tab.
 function trigger_snmpportfinder ()
 {
 
index bba0202..1f88806 100644 (file)
@@ -179,11 +179,9 @@ ENDOFTEXT
 ,
 );
 
-// At the moment we assume that for any two releases we can
-// sequentally execute all batches that separate them, and
-// nothing will break. If this changes one day, the function
-// below will have to generate smarter upgrade paths, while
-// the upper layer will remain the same.
+// This function currently implements a convention that to upgrade any release R1
+// to a release R2 (such that R2 > R1) it takes to apply the sequence of batches
+// (R1, R2] to database R1.
 // Returning an empty array means that no upgrade is necessary.
 // Returning NULL indicates an error.
 function getDBUpgradePath ($v1, $v2)