Add more contract linting rules (#355)

* lint function comments

* check for aligned parameters

Author: Brendan Chou

contracts/margin/Margin.sol

@@ -485,7 +485,7 @@ contract Margin is
     /**
      * Cancel an amount of a loan offering. Only callable by the loan offering's payer or signer.
      *
-     * @param  addresses  Array of addresses:
+     * @param  addresses     Array of addresses:
      *
      *  [0] = owedToken
      *  [1] = heldToken
@@ -498,7 +498,7 @@ contract Margin is
      *  [8] = loan lender fee token
      *  [9] = loan taker fee token
      *
-     * @param  values256  Values corresponding to:
+     * @param  values256     Values corresponding to:
      *
      *  [0] = loan maximum amount
      *  [1] = loan minimum amount
@@ -508,15 +508,15 @@ contract Margin is
      *  [5] = loan expiration timestamp (in seconds)
      *  [6] = loan salt
      *
-     * @param  values32  Values corresponding to:
+     * @param  values32      Values corresponding to:
      *
      *  [0] = loan call time limit (in seconds)
      *  [1] = loan maxDuration (in seconds)
      *  [2] = loan interest rate (annual nominal percentage times 10**6)
      *  [3] = loan interest update period (in seconds)
      *
-     * @param  cancelAmount     Amount to cancel
-     * @return                  Amount that was canceled
+     * @param  cancelAmount  Amount to cancel
+     * @return               Amount that was canceled
      */
     function cancelLoanOffering(
         address[10] addresses,
@@ -565,7 +565,7 @@ contract Margin is
      *  [5] = loan expiration timestamp (in seconds)
      *  [6] = loan salt
      *
-     * @param  values32  Values corresponding to:
+     * @param  values32   Values corresponding to:
      *
      *  [0] = loan call time limit (in seconds)
      *  [1] = loan maxDuration (in seconds)
@@ -590,9 +590,9 @@ contract Margin is
     }
 
     /**
-     * Transfer ownership of a loan to a new address. This new address will be entitled
-     * to all payouts for this loan. Only callable by the lender for a position. If the "who"
-     * param is a contract, it must implement the LoanOwner interface.
+     * Transfer ownership of a loan to a new address. This new address will be entitled to all
+     * payouts for this loan. Only callable by the lender for a position. If "who" is a contract, it
+     * must implement the LoanOwner interface.
      *
      * @param  positionId  Unique ID for the position
      * @param  who         New owner of the loan
@@ -612,8 +612,8 @@ contract Margin is
 
     /**
      * Transfer ownership of a position to a new address. This new address will be entitled to all
-     * payouts. Only callable by the owner of a position. If the "who" param is a contract, it must
-     * implement the PositionOwner interface.
+     * payouts. Only callable by the owner of a position. If "who" is a contract, it must implement
+     * the PositionOwner interface.
      *
      * @param  positionId  Unique ID for the position
      * @param  who         New owner of the position

util/lintcontracts.py

@@ -91,6 +91,69 @@ def lintCommentHeader(dir, filepath, solidityVersion):
     return everythingOkay
 
 
+def lintFunctionComments(dir, filepath):
+    fileName = os.path.basename(filepath)
+    everythingOkay = True
+    inBlockComment = False
+    seenBlank = False
+    alreadyComplained = False
+    argColumn = 0
+    i = 1
+    for line in open(filepath, 'r').readlines():
+        words = line.split()
+        errorSuffix = " (" + fileName + ":" + str(i) + ")"
+        lstripped = line.lstrip()
+
+        # check for extra statements
+        if ('param ' in lstripped and 'param  ' not in lstripped):
+            everythingOkay = False
+            print "Param has only one space" + errorSuffix
+        if ('param   ' in lstripped):
+            everythingOkay = False
+            print "Param has more than two spaces" + errorSuffix
+
+        # start block comment
+        if (not inBlockComment and lstripped.startswith('/**')):
+            argColumn = 0
+            inBlockComment = True
+            seenBlank = False
+            alreadyComplained = False
+
+        # check for aligned parameters
+        if (inBlockComment):
+            col = 0
+            if ('param' in lstripped and len(words) >= 4):
+                col = line.find(' '+words[3]) + 1
+            if ('@returns' in lstripped):
+                col = line.find(words[2])
+            if (col > 0):
+                if (argColumn == 0):
+                    argColumn = col
+                else:
+                    if (col != argColumn):
+                        everythingOkay = False
+                        print "Params not aligned to column " + str(argColumn + 1) + errorSuffix
+
+        # blank comment line
+        if (inBlockComment and lstripped.rstrip() == '*'):
+            seenBlank = True
+
+        # make sure a blank comment line has been found before parameter list
+        if (inBlockComment and not seenBlank):
+            if ('*  param' in lstripped or '* @param' in lstripped):
+                if (not alreadyComplained):
+                    alreadyComplained = True
+                    everythingOkay = False
+                    print "No blank line before param list in function comment" + errorSuffix
+
+        # end block comment
+        if (inBlockComment and line.rstrip().endswith('*/')):
+            inBlockComment = False
+        i += 1
+
+    return everythingOkay
+
+
 def main():
     files = []
     start_dir = os.getcwd()
@@ -109,6 +172,7 @@ def main():
 
     everythingOkay = True
     for file in files:
+        everythingOkay &= lintFunctionComments(dir_path, file)
         everythingOkay &= lintImports(dir_path, file)
         everythingOkay &= lintCommentHeader(dir_path, file, "0.4.24")