documentation style - 2nd/3rd person tense for function comments

[David Manura <dm.lua@...>]

Should comments for Lua functions be written in the 3rd person
declarative or 2nd person imperative?

  -- Adds an element to an array.  [declarative]
  -- Add an element to an array.   [imperative]
  function tinsert(t, x) . . . end

The declarative style is followed by notable examples such as the Lua
Reference Manual [1], lpeg, luafilesystem, luasql, sputnik, iup, and
luajit/BitOp.  However, imperative exceptions currently include
penlight, stdlib, luarocks, and metalua.  In comparison, the Javadoc
style guide recommends declarative [2].  Perl perlfunc is declarative
[3], though styles vary.  The Python core tends to favor imperative
[5], but it's not altogether consistent [6-8].  Drupal has more
comments on this [4].  Overall, the declarative style seems much more
established, and the fact that the Lua Reference Manual uses it is
also very important.

Personally, I've long favored the declarative form, and there are
reasons for it in Lua, such as functions being first class objects
with delayed execution.  Observe the difference:

  -- swaps buffers
  local function swap() abuf, bbuf = bbuf, abuf end

  -- swap buffers
  swap()

The first statement defines a function that, when called, swaps the
buffers.  The second statement actually performs that action.

For these reasons I recommend standardization on the declarative form
(with penlight being the original impetus for this post).

[1] http://www.lua.org/manual/5.2/manual.html#6
[2] http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide
[3] http://perldoc.perl.org/perlfunc.html
[4] http://drupal.org/node/487802#comment-1720946
[5] http://www.python.org/dev/peps/pep-0257/
[6] http://google-styleguide.googlecode.com/svn/trunk/pyguide.html
[7] http://wiki.zope.org/zope3/InterfaceStyle
[8] http://docs.python.org/library/zlib.html