Cleaned up nep1 and simplified the style choices offered by it.

doc/nep1.rst

@@ -1,7 +1,7 @@
 ==============================================
 Nim Enhancement Proposal #1 - Standard Library Style Guide
 ==============================================
-:Author: Clay Sweetser
+:Author: Clay Sweetser, Dominik Picheta
 :Version: |nimversion|
 
 .. contents::
@@ -76,11 +76,13 @@ changed in the future.
   are not required to.
 
   .. code-block:: nim
+    # Constants can start with either a lower case or upper case letter.
     const aConstant = 42
     const FooBar = 4.2
 
-    var aVariable = "Meep"
+    var aVariable = "Meep" # Variables must start with a lowercase letter.
 
+    # Types must start with an uppercase letter.
     type
       FooBar = object
 
@@ -95,13 +97,16 @@ changed in the future.
 
   .. code-block:: nim
     type
-      Handle = int64 # Will be used most often
+      Handle = object # Will be used most often
+        fd: int64
       HandleRef = ref Handle # Will be used less often
+
 - Exception and Error types should have the "Error" suffix.
 
   .. code-block:: nim
     type
       UnluckyError = object of Exception
+
 - Unless marked with the `{.pure.}` pragma, members of enums should have an
   identifying prefix, such as an abbreviation of the enum's name.
 
@@ -112,6 +117,7 @@ changed in the future.
         pcLinkToDir
         pcFile
         pcLinkToFile
+
 - Non-pure enum values should use camelCase whereas pure enum values should use
   PascalCase.
 
@@ -122,91 +128,62 @@ changed in the future.
         LinkToDir
         File
         LinkToFile
+
 - In the age of HTTP, HTML, FTP, TCP, IP, UTF, WWW it is foolish to pretend
-  these are somewhat special words requiring all uppercase. Instead tread them as what they are: Real words. So it's ``parseUrl`` rather than ``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc.
+  these are somewhat special words requiring all uppercase. Instead treat them
+  as what they are: Real words. So it's ``parseUrl`` rather than
+  ``parseURL``, ``checkHttpHeader`` instead of ``checkHTTPHeader`` etc.
 
 
 Coding Conventions
 ------------------
 
-- The 'return' statement should only be used when its control-flow properties
+- The 'return' statement should ideally be used when its control-flow properties
-  are required. Use a procedure's implicit 'result' variable instead. This
+  are required. Use a procedure's implicit 'result' variable whenever possible.
-  improves readability.
+  This improves readability.
 
-- Prefer to return `[]` and `""` instead of `nil`, or throw an exception if
+  .. code-block:: nim
-  that is appropriate.
+    proc repeat(text: string, x: int): string =
+      result = ""
+
+      for i in 0 .. x:
+        result.add($i)
 
 - Use a proc when possible, only using the more powerful facilities of macros,
   templates, iterators, and converters when necessary.
 
-- Use the 'let' statement (not the var statement) when declaring variables that
+- Use the ``let`` statement (not the ``var`` statement) when declaring variables that
-  do not change within their scope. Using the let statement ensures that
+  do not change within their scope. Using the ``let`` statement ensures that
   variables remain immutable, and gives those who read the code a better idea
   of the code's purpose.
 
-- For new types, it is usually recommended to have both 'ref' and 'object'
-  versions of the type available for others to use. By making both variants
-  available for use, the type may be allocated both on the stack and the heap.
-
 
 Conventions for multi-line statements and expressions
 -----------------------------------------------------
 
-- Any tuple type declarations that are longer than one line should use the
+- Tuples which are longer than one line should indent their parameters to
-  regular object type layout instead. This enhances the readability of the
+  align with the parameters above it.
-  tuple declaration by splitting its members' information across multiple lines.
 
   .. code-block:: nim
     type
-      ShortTuple = tuple[a: int, b: string]
+      LongTupleA = tuple[wordyTupleMemberOne: int, wordyTupleMemberTwo: string,
+                         wordyTupleMemberThree: float]
 
-      ReallyLongTuple = tuple
+- Similarly, any procedure and procedure type declarations that are longer#
-        wordyTupleMemberOne: string
+  than one line should do the same thing.
-        wordyTupleMemberTwo: int
-        wordyTupleMemberThree: double
-- Similarly, any procedure type declarations that are longer than one line
-  should be formatted in the style of a regular type.
 
   .. code-block:: nim
     type
-      EventCallback = proc (
+      EventCallback = proc (timeReceived: Time, errorCode: int, event: Event,
-        timeRecieved: Time
+                            output: var string)
-        errorCode: int
-        event: Event
-      )
-- Multi-line procedure declarations/argument lists should continue on the same
-  column as the opening brace. This style is different from that of procedure
-  type declarations in order to distinguish between the heading of a procedure
-  and its body. If the procedure name is too long to make this style
-  convenient, then one of the styles for multi-line procedure calls (or
-  consider renaming your procedure).
 
-  .. code-block:: nim
     proc lotsOfArguments(argOne: string, argTwo: int, argThree: float
                          argFour: proc(), argFive: bool): int
                         {.heyLookALongPragma.} =
-- Multi-line procedure calls should either have one argument per line (like
+
-  multi-line type declarations) or continue on the same column as the opening
+- Multi-line procedure calls should continue on the same column as the opening
-  parenthesis (like multi-line procedure declarations).  It is suggested that
+  parenthesis (like multi-line procedure declarations).
-  the former style be used for procedure calls with complex argument
-  structures, and the latter style for procedure calls with simpler argument
-  structures.
 
   .. code-block:: nim
-    # Each argument on a new line, like type declarations
-    # Best suited for 'complex' procedure calls.
-    readDirectoryChangesW(
-      directoryHandle.THandle,
-      buffer.start,
-      bufferSize.int32,
-      watchSubdir.WinBool,
-      filterFlags,
-      cast[ptr dword](nil),
-      cast[Overlapped](ol),
-      cast[OverlappedCompletionRoutine](nil)
-    )
-
-    # Multiple arguments on new lines, aligned to the opening parenthesis
-    # Best suited for 'simple' procedure calls
     startProcess(nimExecutable, currentDirectory, compilerArguments
                  environment, processOptions)