Re: [ANN] LDoc 1.4 RC1

["Gary V. Vaughan" <gary@...>]

Hi Steve,

First of all, I'm very happy with the new additions to LDoc.  Thanks for
all your hard work on this.

That said, I'm still struggling to move lua-stdlib over to LDoc -- possibly
because I haven't understood the correct way to mark the sources up.

Here's a simplified example of what I have in std/table.lua:


--- Extended table object management.
-- @classmod std.table
-- @alias Table

local base = require "std.base"

--- Make a shallow copy of *table*, including any metatable.
-- @function clone
-- @param nometa if non-nil, don't copy metatable
-- @return shallow copy of *table*
-- @see std.tree:clone
local clone = base.clone

--- Turn a tuple into a list.
-- @param ... tuple
-- @return list
local function pack (...)
  return {...}
end

--- Like `table.sort`, but returning the result.
-- @tparam function c comparator function
-- @return sorted *table*
local function sort (self, c)
  table.sort (self, c)
  return self
end

--- @export
local Table = {
  clone = clone,
  pack  = pack,
  sort  = sort,
}

-- Copy functionality from core table module.
for k,v in pairs (table) do
  Table[k] = Table[k] or v
end

return Table


Here are the issues I encountering with this style:

1. Recall that I've had to pull a handful of functions out of their natural
   homes and implement them in a shared `std.base` module to prevent reference
   loops during require.  I couldn't get `@within std.tree` to let me put the
   doc-comments above the actual implementation in `std/base.lua`, but display
   the html in the std.table page. (base.lua is an implementation detail that
   the user shouldn't be bothered by).

   Also using @submodule puts the docs from base.lua in a separate section
   rather than merging them directly into the right place (plus base.lua
   has bits from tree.lua and list.lua as well as table.lua, so that's really
   not the right approach anyway).

   I worked around that by adding the doc-comments above the import statement,
   but there's no way to tell LDoc whether clone is an object method,
   `std.table:clone` or a class method `std.table.clone`.

2. There's no distinction between class methods and object methods even when
   the parameters are visible to LDoc, every entry is always documented as e.g.
   `std.table:pack (...)`, where only the functions that use self as the first
   parameter should be shown with `:` sugar: pack is *always* called as a class
   method `std.table.pack (...)`.

   Even adding `@function pack`, or `@function std.table.pack` doesn't help.

3. Although `std.table:sort` appears in the documentation with `:`, the fact
   that I deliberately haven't documented the self parameter throws an error:

     sort: param and formal argument mismatch: 'c' 'self'
     sort: undocumented formal argument: 'c'

   Even so, the documentation shows the self parameter, as well as the `:`
   sugar, which is clearly confusing, and IMHO wrong:

     std.table:sort (self)

I tried to make patches, but there's a lot of complicated code in LDoc that
I didn't learn my way around.

Are these things I can work around?  Or have I uncovered bugs in the RC?

Cheers,
Gary

On Sep 21, 2013, at 12:51 AM, steve donovan <steve.j.donovan@gmail.com> wrote:

> This is a fresh version of LDoc[1], the luadoc-compatible Lua
> documentation generator.
> 
> First of all, thanks to Alexander Gladysh for pushing this release and
> doing quality checking!
> 
> A list of changes is here [0] but the main things (apart from some
> nasty bugs squashed) is that you can sort items in sections using
> 'sort=true'.  Using the new @set tag, you can even sort only in a
> particular module using '@set sort=true' in the module comment; this
> applies also to any parameter controlling output generation.
> 
> There is a new alternative 'pale' theme, which I've used for [1]
> 
> One of the innovations that Alexander has been pushing for is support
> for _return groups_, which allow a documenter to specify that a
> function can return different _sets_ of values [3]. The new @error tag
> makes the common pattern 'either return a value, or return nil and an
> error' easier to document.
> 
> It is possible to directly generate Markdown, although currently only
> for single files; this is '--ext md' (this feature is for Dirk, who
> could not see the purpose of the old meaning of '--ext'.
> 
> There is experimental support for Moonscript and plain C files,
> although I imagine this will not be of such great interest to most
> users; it was mostly an exercise in making the front-end flexible
> enough to handle rather different languages.
> 
> Give it a bash, and in a few days I'll put a final 1.4.1 up in the
> luarocks repo.
> 
> To install:
> 
> $ sudo luarocks install
> http://stevedonovan.github.io/files/ldoc-1.4.0-1.rockspec
> 
> Or, grab the tagged 1.4.0 release with [2].  Make sure you have Penlight.
> Unpack it somewhere (/my/path/ldoc-1.4.0) and make a little script
> ldoc like so on your path
> 
> lua /my/path/ldoc-1.4.0/ldoc.lua "$@"
> 
> or ldoc.bat
> 
> @echo off
> lua \my\path\ldoc-1.4.0\ldoc.lua %*
> 
> You can then go to /my/path/ldoc-1.4.0/doc and run 'ldoc .' to build
> the documentation.
> 
> [0] https://github.com/stevedonovan/LDoc/blob/master/changes.md
> [1] http://stevedonovan.github.io/ldoc/
> [2] https://github.com/stevedonovan/LDoc/releases
> [3] http://stevedonovan.github.io/ldoc/examples/multiple.lua.html
> 
> output is here: http://stevedonovan.github.io/ldoc/examples/multiple/
>

Attachment: signature.asc
Description: Message signed with OpenPGP using GPGMail