Grid uses .docmeta to update the main description from its README file. It will overwrite any content that is already on the page.
I would assume the page will be created if it doesn't already exist, though this would be trivial for you to test.
If you're creating a file just for documentation, Lua with comments doesn't seem like a good format. Just use Markdown or another syntax that's actually designed for writing and formatting human-readable text.
Just before I went to work, I got SVN working again. I tried a few things like turning the repo off and back on and other ideas. The one that seems to have worked is go into TortoiseSVN's Settings, Advanced, and clear the field AllowAuthSave. Don't just set to true or false; I had to clear it altogether, then everything worked.
I am still getting stumped by docmeta, which is back on topic I suppose. I'll post the code and see if anyone can spot what I am missing. The only thing I haven't tried is putting @class at the top of my file. I have tried variants of the docmeta, such as "" around LibMapPins-1.0.lua and no quotes around API, combinations of both or neither.
--- Place an icon on the world map frame.
-- @paramsig MyAddOn:CreatePinByMapID(icon, x, y, mapID, [mapFloor]).
-- @param icon Path to icon file (string).
-- @param x Horizontal XX.xx coordinate for the icon (number).
-- @param y Vertical YY.yy coordinate for the icon (number).
-- @param mapID The mapID (number).
-- @param (optional) mapFloor The map floor, default 0 (number).
-- @return pin Shown on the world map, table of input values.
-- @usage -- Put an icon in Cleft of Shadow, Orgrimmar
-- local MyPin = MyAddOn:CreatePinByMapID(icon, 22.84, 13.56, 321, 1).
local function CreatePinByMapID(icon, x, y, mapID, mapFloor)
How sparse (as in, the amount of negative space) the output of that is, and...
How ugly and bulky the LuaDoc header comments look in the code.
I might just consider what Phanx suggested and come up with my own more-condensed and less-airy documentation format, should I ever make anything with a public API.
WRT (2), though: it is possible that, after staring at .NET XML documentation for almost 8 years now, anything else would just be automatically "ugly and bulky", regardless of its syntactic quality or its verbosity.