add the apis.txt table to nep1.rst

doc/nep1.rst

@@ -60,7 +60,7 @@ Spacing and Whitespace Conventions
 
 
 Naming Conventions
--------------------------
+------------------
 
 Note: While the rules outlined below are the *current* naming conventions,
 these conventions have not always been in place. Previously, the naming
@@ -147,6 +147,80 @@ changed in the future.
   an in-place version should get an ``-In`` suffix (``replaceIn`` for this example).
 
 
+The stdlib API is designed to be **easy to use** and consistent. Ease of use is
+measured by the number of calls to achieve a concrete high level action. The
+ultimate goal is that the programmer can *guess* a name.
+
+The library uses a simple naming scheme that makes use of common abbreviations
+to keep the names short but meaningful.
+
+
+-------------------     ------------   --------------------------------------
+English word            To use         Notes
+-------------------     ------------   --------------------------------------
+initialize              initT          ``init`` is used to create a
+                                       value type ``T``
+new                     newP           ``new`` is used to create a
+                                       reference type ``P``
+find                    find           should return the position where
+                                       something was found; for a bool result
+                                       use ``contains``
+contains                contains       often short for ``find() >= 0``
+append                  add            use ``add`` instead of ``append``
+compare                 cmp            should return an int with the
+                                       ``< 0`` ``== 0`` or ``> 0`` semantics;
+                                       for a bool result use ``sameXYZ``
+put                     put, ``[]=``   consider overloading ``[]=`` for put
+get                     get, ``[]``    consider overloading ``[]`` for get;
+                                       consider to not use ``get`` as a
+                                       prefix: ``len`` instead of ``getLen``
+length                  len            also used for *number of elements*
+size                    size, len      size should refer to a byte size
+capacity                cap
+memory                  mem            implies a low-level operation
+items                   items          default iterator over a collection
+pairs                   pairs          iterator over (key, value) pairs
+delete                  delete, del    del is supposed to be faster than
+                                       delete, because it does not keep
+                                       the order; delete keeps the order
+remove                  delete, del    inconsistent right now
+include                 incl
+exclude                 excl
+command                 cmd
+execute                 exec
+environment             env
+variable                var
+value                   value, val     val is preferred, inconsistent right
+                                       now
+executable              exe
+directory               dir
+path                    path           path is the string "/usr/bin" (for
+                                       example), dir is the content of
+                                       "/usr/bin"; inconsistent right now
+extension               ext
+separator               sep
+column                  col, column    col is preferred, inconsistent right
+                                       now
+application             app
+configuration           cfg
+message                 msg
+argument                arg
+object                  obj
+parameter               param
+operator                opr
+procedure               proc
+function                func
+coordinate              coord
+rectangle               rect
+point                   point
+symbol                  sym
+literal                 lit
+string                  str
+identifier              ident
+indentation             indent
+-------------------     ------------   --------------------------------------
+
+
 Coding Conventions
 ------------------