lunarmodules / ldoc Goto Github PK

Hi Steve,

I am actually facing to some (quite frustrating) issues with inline reference using @{tag} or backticks. Let's say that I have this layout for the code:

(Root Folder)
-- file lib.lua
-- (folder) core
---- (file) log.lua

File log.lua implements a class (class log). Top level file lib.lua also implements a class.
Normally, without using explicitely the @module tag in any file header, LDoc would infer the module name. What will result, in the HTML output the following modules : Module lib, Module core.log. What is absolutely perfect.
(I have to mention here that, in each file, to declare the class being documented, I am using the tag @type).

Since the exact submodule name is core.log, LDOc assumes that inlining log (with backticks) would refer to some piece of code that exists within file core.log.lua.
So, is there a possible workaround this ? So that I can write log (with backticks) or @{log} in lib.lua and still have a reference to the very module core.log ?

Best regards,
Roland

Since update to 1.3a, I'm unable to build awesome 3.5.

lua: /usr/share/lua/5.2/ldoc/html.lua:41: attempt to index local 'm' (a nil value)
stack traceback:
/usr/share/lua/5.2/ldoc/html.lua:41: in function 'get_module_info'
/usr/share/lua/5.2/ldoc/html.lua:171: in function 'generate_output'
/usr/bin/ldoc.lua:597: in main chunk
[C]: in ?
make[2]: *** [CMakeFiles/ldoc] Error 1
make[1]: *** [CMakeFiles/ldoc.dir/all] Error 2
make: *** [all] Error 2

Issue was probably added in commit 1bb8392.

When splitting modules into multiple files, it is impossible to get an overall alphabetically sorted function list in the merged documentation for that module, unless I split up the functions to the multiple files by alphabetical needs instead of senseful categories (which I wouldn't want to do obviously). By sorting in-file, I can only get partial list sections sorted but not the module as a whole.

Therefore, alphabetic sorting support in LDoc should be added.

It would be good if it was possible to make exceptions, e.g. I would always want the "new" and "delete" functions of my class types first, then all the other functions alphabetically sorted.

One universal and very flexible way of specifying this would be to specify a sort function in the config.ld which takes two function names (or other sort of member's names) and returns true if the first comes before the second, and false if the second comes before the first:

sortfunc.mymodule.mytype = function(first, second)
    -- exceptions:
    if first == "new" then
        return true
    elseif first == "delete" then
        if second == "new" then
            return false
        end
        return true
    elseif second == "new" then
        return false
    elseif second == "delete" then
        return false
    end
    -- regular sorting:
    if table.sort({first, second})[1] == first then
        return true
    else
        return false
    end
end

See the generated documentation for the LDoc script at http://stevedonovan.github.com/ldoc/index.html

The generated HTML doesn't quote the brackets in the line:

<file> (string) source file or directory containing source

Running on Ubuntu 10.04.3 LTS, I got penlight installed using luarocks.
Using ldoc 0.4.2 and Lua 5.1.4.
My ldoc script is lua /path/to/ldoc/ldoc.lua $*

When using ldoc without config.ld on:

ldoc mod2.lua
output written to docs/`

Same source, but config.ld present:

ldoc mod2.lua
reading configuration from /home/lbarthelemy/Documents/tools/LDoc-0.4.2/tests/md-test/config.ld
lua: ...home/lbarthelemy/Documents/tools/LDoc-0.4.2/ldoc.lua:106: attempt to call global 'loadin' (a nil value)
stack traceback:
...home/lbarthelemy/Documents/tools/LDoc-0.4.2/ldoc.lua:106: in function 'read_ldoc_config'
...home/lbarthelemy/Documents/tools/LDoc-0.4.2/ldoc.lua:450: in main chunk
[C]: ?

Looking into ldoc.lua source, looks like loadin should be defined by penlight, but I did not find in Penlight.

Maybe I've badly installed/configured ldoc/penlight...

Steve,

I have added a new set of features to the LDoc code and wanted to pass them on for integration assuming you find it as useful as I do. I have added the ability to embed images or generate UML diagrams and embed the image in the document.

The UML can be part of a LDoc section using the syntax from plantUml or various other text to UML parsers. I setup plantUml as the default. This allows the user to embed nice UML images in the generated documents by using simple text within you code comments. For example embedding a UML sequence diagram by using:

--- @startuml
--- a->b:test request
--- a<-b:test response
--- @enduml

I have added the ability to alter some of the default capability by adding some JSON text after the "@startuml" tag. The options are:

-- "exec":"path"         

-- This allows you to alter the UML generation engine and path for execution. You can specify a different path/executable for the UML parser. For example,
"exec":"/usr/bin/msvc %s"
NOTE: The "%s" is where the temp UML text will be placed (within a temp file). The default is "plantuml %s".

-- "removeTags":true

-- if true (no quotes), the @startuml and @enduml are removed, this makes it possible to support other UML parsers that do not use these tags. The default is false.

-- "fileType":"gif"

-- This defines a different file type that is generated by the UML parsers. The default is "png", but you can specify a "gif" (for example) if the UML parser generates a png.

Again, I have tested with plantUml but have hopefully left it flexible enough to use different UML parsers.

I also added the ability to embed images in your generated documents. To embed an image you add:
@embed_XXX{"/path/to/file.XXX"} XXX specifies the extension type. For example,

@embed_gif{"tmp/test.gif"}

This will embed the base64 image in the document.

This does add a dependency to Lua sockets. However, if the module is not found it will just report the error.

I have tried to follow the original intent of the code. I preprocess the text prior to extracting tags. So there is no use for adding tags or anything. This way the original tag handling stays intact. I'd love to see this as part of the latest source code. Please let me know what you think.

Tysen Moore

Diff is:

diff --git a/ldoc/parse.lua b/ldoc/parse.lua
index 5bebc3a..28102f1 100644
--- a/ldoc/parse.lua
+++ b/ldoc/parse.lua
@@ -6,6 +6,21 @@ local tools = require 'ldoc.tools'
 local doc = require 'ldoc.doc'
 local Item,File = doc.Item,doc.File

+-- This functionality is only needed for UML support.
+-- If this does not load it will only trigger a failure
+-- if the UML syntax was detected.
+local bOk, http   = pcall( require, "socket.http")
+local mime        = nil
+if bOk == false then
+   http = nil
+else
+   bOk, mime   = pcall( require, "mime")
+   if bOk == false then
+      mime = nil
+   end
+end
+
+
 ------ Parsing the Source --------------
 -- This uses the lexer from PL, but it should be possible to use Peter Odding's
 -- excellent Lpeg based lexer instead.
@@ -46,6 +61,138 @@ function parse_tags(text)
    return preamble,tag_items
 end

+-- Used to preprocess the tag text prior to extracting
+-- tags.  This allows us to replace tags with other text.
+-- For example, we embed images into the document.
+local function preprocess_tag_strings( s )
+
+   local function create_embedded_image( filename, fileType )
+
+      local html = ""
+
+      if mime == nil then
+         local errStr = "LDoc error, Lua socket/mime module needed for UML"
+         -- Just log the error in the doc
+         html = "<b><u>"..errStr.."</u></b>"
+         print(errStr)
+         return html
+      end
+
+      if fileType == nil then
+         fileType = "png"
+      end
+
+      -- Now open the new image file and embed it
+      -- into the text as an HTML image
+      local fp = io.open( filename, "r" )
+      if fp then
+         -- This could be more efficient instead of
+         -- reading all since the definitions are
+         -- typically small this will work for now
+         local img = fp:read("*all")
+         fp:close()
+
+         html = string.format( '<img src="data:image/%s;base64,%s" />', fileType, mime.b64( img ) )
+      else
+         local errStr = string.format("LDoc error opening %s image file: %q", fileType, filename)
+         -- Just log the error in the doc
+         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
+         print(errStr)
+      end
+
+      return html
+   end
+
+   ----------------------------------------------------------
+   -- Embedded UML
+   ------------------
+   local epos
+   local execPath = "plantuml %s"
+   local spos     = string.find(s, "@startuml")
+   if spos then
+      _, epos = string.find(s, "@enduml")
+   end
+
+   if spos and epos then
+
+      local filename = os.tmpname()
+      local sUml     = string.sub(s,spos,epos) -- UML definition text
+
+      -- Grab the text before and after the UML definition
+      local preStr   = string.match(s, "(.*)@startuml")
+      local postStr  = string.match(s, "@enduml(.*)")
+      local fileType = "png"
+      local fp       = io.open( filename, "w" )
+      local html     = ""
+
+      --Add support for optional formatting in a json format
+      if string.sub( sUml, 10,10 ) == "{" then
+         local sFmt = string.match( sUml, ".*{(.*)}" )
+
+         -- Remove the formatter
+         sUml = string.gsub( sUml, ".*}", "@startuml" )
+
+         -- To avoid adding the dependency of JSON we will
+         -- parse what we need.
+
+         -- "exec":"path"
+         -- This allows you to alter the UML generation engine and path for execution
+         execPath = string.match(sFmt, '.-"exec"%s-:%s-"(.*)".-') or execPath
+
+         -- "removeTags":true
+         -- if true, the @startuml and @enduml are removed, this
+         -- makes it possible to support other UML parsers.
+         sRemoveTags = string.match(sFmt, '.-"removeTags"%s-:%s-(%a*).-')
+         if sRemoveTags == "true" then
+            sUml = string.gsub( sUml, "^%s*@startuml", "" )
+            sUml = string.gsub( sUml, "@enduml%s*$", "" )
+         end
+
+         -- "fileType":"gif"
+         -- This defines a different file type that is generated by
+         -- the UML parsers.
+         fileType = string.match(sFmt, '.-"fileType"%s-:%s-"(.*)".-') or fileType
+      end
+
+      if fp then
+         -- write the UML text to a file
+         fp:write( sUml )
+         fp:close()
+
+         -- create the diagram, overwrites the existing file
+         os.execute( string.format(execPath, filename ) )
+
+         -- create the embedded text for the image
+         html = create_embedded_image( filename, fileType )
+
+         os.remove( filename ) -- this is the PNG from plantUml
+      else
+         local errStr = "LDoc error creating UML temp file"
+         -- Just log the error in the doc
+         html = "<br><br><b><u>"..errStr.."</u></b><br><br>"
+         print(errStr)
+      end
+      s = preStr..html..postStr
+
+   end -- embed UML
+
+   ----------------------------------------------------------
+   -- Embedded Image
+   ------------------
+   local fileType, filename = string.match(s, '@embed_(.*){"(.*)"}')
+   if fileType and filename then
+
+      -- create the embedded text for the image
+      html = create_embedded_image( filename, fileType )
+
+      s = string.gsub(s, "@embed_.*{.*}", html)
+
+   end -- embedded image
+
+   return s
+
+end -- preprocess_tag_strings
+
 -- This takes the collected comment block, and uses the docstyle to
 -- extract tags and values.  Assume that the summary ends in a period or a question
 -- mark, and everything else in the preamble is the description.
@@ -53,6 +200,9 @@ end
 -- Alias substitution and @TYPE NAME shortcutting is handled by Item.check_tag
 local function extract_tags (s)
    if s:match '^%s*$' then return {} end
+
+   s = preprocess_tag_strings( s )
+
    local preamble,tag_items = parse_tags(s)
    local strip = tools.strip
    local summary, description = preamble:match('^(.-[%.?])(%s.+)')

I have examples organized into several directories, in increasing order of "difficulty." LDoc faithfully recurses through all of them, but just globally alphabetizes them. It would be nice if the directory structure were reproduced.

Is LDoc supposed to take multiple files at once?
Because when I do:

ldoc src/filewithvalidldoccomments.c src/filewithoutanydoccomments.c

.. then I get usable output. However, when I'm doing this:

ldoc src/filewithoutanydoccomments.c src/filewithvalidldoccomments.c

.. I end up with an empty documentation (just the doc site template but no modules/content whatsoever).

I'm using (abusing?) ad hoc sections for documenting class instance variables, like so:

--- Instance fields. These can be set only for an buffer instance, and not
-- globally for the module.
-- @section instance

--- foo is bar,  blah blah
foo = nil

--- @section end

This worked fine for the first file, but when doing the same for a second file in the module this results in duplicated documentation for the contained fields (e.g. for the example above you get two "Instance fields" headers each containing the same duplicate documentation for foo. Some investigation reveals that it's having the same deduced section name ("Instance fields" in this case) which caused the issue, and that renaming it for one of the files avoid the issue.

This is for master.

The function tag does not support tag modifier.
If I run ldoc on this code :

---
-- @function[foo=bar] myfunc
-- My func is a great function
local function myfunc()
    print "foo"
end

ldoc give me a parse error (test.lua:8: ?: 'name' cannot have multiple values)

When I use new_type in config.ld like in the documentation

new_type("macro", "Macros")

and define a field (or param)

-------
-- A usefull macro.
--@macro first_macro
--@field test a field but only with colon as headline instead of "Field:"

I get a colon as title for the field section:

Guys, I would like to close remaining issues for 1.3 so we can do a proper release and finally replace the ancient LuaRocks version. Last minute features are not out of the question, provided they don't involve tearing up the floorboards.

I apologize if this is already possible, but the way I tried it didn't work:

// @usage -- play sound file "blubber.ogg" at 80% volume and
// -- fade in for 5 seconds
// mysound2 = @{blitwizard.audio.simpleSound:new}("blubber.ogg")
// mysound2:play(0.8, 8)

My expectation was that the function name would become clickable so that the user can instantly jump to that particular function by clicking its name inside the example code. However, I end up with @{blitwizard.audio.simpleSound:new} literally appearing inside the example code.

Currently LDoc complains if two files declare that they are the same module. Since LDoc claims that it wants to make modules more flexible it would be nice to have the two files be "merged" into one module. This is because sometimes the file layout is different than the logical code layout for whatever reason.

There are also other advantages to this such as creating a /dev/null style module that files can join if they do not want to be a part of the documentation. This way you don't have to specify every file on the command line but are still able to hide files.

When using markdown/discount, in-line links with underscores are not properly escaped. I'm not going to issue a pull request for this; the patch I use is to copy the escape code from right above it:

diff --git a/ldoc/markup.lua b/ldoc/markup.lua
index 0e60717..ae49602 100644
--- a/ldoc/markup.lua
+++ b/ldoc/markup.lua
@@ -43,6 +43,9 @@ local function resolve_inline_references (ldoc, txt, item, plain)
       res  = res:gsub('`([^`]+)`',function(name)
          local ref,err = markup.process_reference(name)
          if ref then
+           if not plain then -- a nastiness with markdown.lua and underscores
+              name = name:gsub('_','\\_')
+           end
             return ('<a href="%s">%s</a> '):format(ldoc.href(ref),name)
          else
             return '`'..name..'`'

For a class (@type) the natural place (IMHO) to suggest a generic usage example is at class level. However, if specified for a @type and not a @function, the @usage tag is completely ignored. It would be very nice if it was usable at class level too!

Is there any way to enable syntax highlighter for source code in docs? I put lxsh today and it works fine, but I have a feeling that it's already there and I just don't see it...

at line 443:
/// Miscelaneous functions.
// @section Miscelaneous
should read:
/// Miscellaneous functions.
// @section Miscellaneous

when I try to parse buitin module, I have this warning :

warning: mypath/builtin/amodule.luadoc contains no items.

for example :

>ldoc -m coroutine
warning: mypath/ldoc/builtin/coroutine.luadoc contains no items
----
module: coroutine       coroutine.

but if I try :

>ldoc -m pl.pretty
----
module: pl.pretty       Pretty-printing Lua tables.
* read(s) - read a string representation of a Lua table.
* write(tbl, space, not_clever) - Create a string representation of a Lua table.

* dump(t, fname) - Dump a Lua table out to a file or stdout.

it seem's ok.

I would like to be able to format parameter comments along the lines of:

--- A function that does really useful stuff.
-- string: text         This parameter accepts a string.
--                      More information that gets appended to the first line.
-- number: magic_number This parameter accepts a number.
--
--                      More information (on a new line) about `magic_number`.
function (text, magic_number)
  ...
end

There are two issues that I see when I try this:

1. The comment for the text parameter ends up in a code block (as it is 'indented' more than four spaces).
2. Any of the additional information lines end up in a code block since they are indented more than four spaces.

I guess this raises two questions for me.

Is this the desired behavior? Do people really put code blocks in parameter descriptions? (I can't recall a single time that I have).

This code fire error

---
-- @module test

---
--
function some_function() end

f:\tmp\test.lua:6: internal LDoc error
G:\lua\5.1\libs\ldoc\lua\ldoc\lang.lua:121: attempt to call method 'add' (a nil value)
stack traceback:
    G:\lua\5.1\libs\ldoc\lua\ldoc\lang.lua:121: in function 'item_follows'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:311: in function <G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:220>
    [C]: in function 'xpcall'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:220: in function 'parse_file'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:342: in function 'file'
    G:\lua\5.1\libs\ldoc\utils\ldoc.lua:338: in function 'process_file'
    G:\lua\5.1\libs\ldoc\utils\ldoc.lua:390: in main chunk
    [C]: ?

We're iteratively documenting our Katamari:

https://github.com/lua-nucleo/lua-nucleo/

As you can see, there is a lot of empty pages in the documentation.

We'd like to see at least list of names of undocumented functions that a module exports. Is it possible? (Probably shouldn't be on by default, should be an option in LDoc config.)

I have this fragment in my README.md:

lua @{test.lua}

where test.lua is a file listed (correctly) as example.

What i see in the generated docs/topics/README.md.html is

<pre>
 lua &lt;a href=<span class="string">"../examples/test.lua.html#"</span>&gt;test.lua&lt;/a&gt;

</pre>

Thus in the page i see the html code for the link

Please note this problem here might be due to a basic misunderstand on my side of how ldoc works, so if that's the case I'm really sorry for wasting your time!

So what happens is that a source code file of mine just contains those doc comments:

///
// @author Jonas Thiem  ([email protected])
// @copyright 2011-2013
// @license zlib
// @module blitwizard

/// Load a .zip file as a resource archive.
//
// All files inside the zip file will be mapped into the local
// folder as resource files, so that you can load them
// as sounds, graphics etc.
//
// E.g. if the archive contains a folder "blubb", and inside
// "sound.ogg", you can just load "blubb/sound.ogg" as a sound
// after loading the archive with this function.
// @function loadResourceArchive
// @tparam string Path to the .zip archive to be loaded

/// Set the stepping frequency of the game logic.
// The default is 16ms. Physics are unaffected.
//
// Please note changing this is a very invasive change
// - don't do this if you don't know what you're doing.
//
// Also, do NOT use this to speed up/slow down your game
// while it runs. While it may work, it will lead to low
// frames per second and you should simply use a speed factor
// in all your logic functions instead.
//
// Generally, bigger stepping times to 16ms can cause
// all sorts of problems (low frames per second, physics
// callbacks triggering oddly late, ...), so this function
// is only useful for some rare cases.
// @function setStep

(code file is at https://github.com/JonasT/Blitwizard/blob/master/src/luafuncs.c )

.. and I end up with setStep and loadResourceArchive being part of my class type "object" in the final documentation: http://www.blitwizard.de/doc-files/modules/blitwizard.html#object:loadResourceArchive

That class type does exist in that namespace, however it is described in another file and those functions are unrelated to it so I don't want them to be considered a part of it.

So I'm not sure what's going on here, either me or ldoc are doing something wrong :)

Rather than blah:

Here's a diff, but you'll have to read the source since github's a bit took keen to markdown it.

$ git diff ldoc/html.lua ldoc/html/ldoc_ltp.lua ldoc/html/ldoc_css.lua 
diff --git a/ldoc/html.lua b/ldoc/html.lua
index 3e00def..ebb411d 100644
--- a/ldoc/html.lua
+++ b/ldoc/html.lua
@@ -102,9 +102,9 @@ function html.generate_output(ldoc, args, project)
       return (tp:gsub('%a[%w_%.]*',function(name)
          local ref,err = markup.process_reference(name)
          if ref then
-            return ('%s '):format(ldoc.href(ref),name)
+            return ('%s'):format(ldoc.href(ref),name)
          else
-            return ''..name..' '
+            return ''..name..''
          end
       end))
    end
diff --git a/ldoc/html/ldoc_css.lua b/ldoc/html/ldoc_css.lua
index e706f85..dc7ab39 100644
--- a/ldoc/html/ldoc_css.lua
+++ b/ldoc/html/ldoc_css.lua
@@ -73,6 +73,10 @@ body {
 }
 
 code, tt { font-family: monospace; }
+span.parameter { font-family:monospace; }
+span.parameter:after { content:":"; }
+span.type:before { content:"("; }
+span.type:after { content:")"; }
 
 body, p, td, th { font-size: .95em; line-height: 1.2em;}
 
diff --git a/ldoc/html/ldoc_ltp.lua b/ldoc/html/ldoc_ltp.lua
index 7e7e1db..76558c2 100644
--- a/ldoc/html/ldoc_ltp.lua
+++ b/ldoc/html/ldoc_ltp.lua
@@ -140,8 +140,12 @@ return [==[
     
$(module.kinds:type_of(item).subnames):
     

 #   for p in iter(item.params) do
+      
$(p)
 #     local tp = ldoc.typename(item:type_of_param(p))
-       
$(p): $(tp)$(M(item.params[p],item))
+#     if tp ~= '' then
+        $(tp)
+#     end
+      $(M(item.params[p],item))
 #   end -- for
     
 #   end -- if params
@@ -161,8 +165,12 @@ return [==[
     
Returns:
     

 #     for i,r in ldoc.ipairs(item.ret) do
+        $(li)
 #       local tp = ldoc.typename(item:type_of_ret(i))
-        $(li)$(tp)$(M(r,item))$(il)
+#       if tp ~= '' then
+          $(tp)
+#       end
+        $(M(r,item))$(il)
 #     end -- for
     
 #   end -- if returns

I updated from LDoc 1.1.0 to 1.2.0 and the documentation in my C++ files is not working properly now.

All I get for any of my C/C++ files is the module header - no other functions/tables/etc.

I added tests/example/mylib.c from the LDoc repository to my project and got LDoc to parse it along with my other lua/cpp files and it behaves the same - I just get the info from the first comment block in the file.

I've tried a variety of workarounds but so far I haven't been able to figure out why LDoc doesn't parse the rest of the file.

LDoc fails when trying to build docs for the LDoc itself.

$ lua -v
Lua 5.1.4  Copyright (C) 1994-2008 Lua.org, PUC-Rio
$ cd /path/to/ldoc
$ lua ldoc.lua .
reading configuration from config.ld
cannot load formatter: discount

Functions with long names and many parameters break function tables.

Since I just added a few new functions with even longer names and even more parameters, it got pretty bad right now :-P a fix would be nice.

I recommend simply changing <td .... nowrap> to <td ....> which will allow the function names & parameters to wrap into multiple lines. This will allow the table to fit into the horizontal space again, and excessively long function names & parameter lists will be usefully line-wrapped.

When invoking ldoc.lua using . (the current directory) as the path module name deduction is failing:

$ ldoc.lua .
reading configuration from config.ld
/full/path/.
module(...) name deduction failed: base /full/path/./ /full/path/file.lua

When using the full path it succeeds. I think the issue is related to the . showing up at the end of the base base path.

I'm using Lua 5.1 and ldoc 1.3.8-2 installed via luarocks.

i have 2 module : odbc.ex.Environment and odbc.ex.Connection
each of them implement its own class.
I wont reference from Environment module to Connection class without specifying whole odbc.ex.Connection.Connection
config.ld:

format='discount'
file = {
  'ex.lua',
  'Environment.lua',
  'Connection.lua',
}
tparam_alias ('Environment','odbc.ex.Environment.Environment')
tparam_alias ('Connection','odbc.ex.Connection.Connection')

Evironment.lua:

...
--- Create new `Connection` object and connect to database.
--
-- - `Connection`          -- <li><a href="../modules/odbc.ex.Environment.html#odbc.ex.Connection">Connection</a> </li>
-- - @{Connection}      -- <li><a href="../modules/odbc.ex.Environment.html#odbc.ex.Connection">?que</a></li>
-- - `odbc.ex.Connection.Connection`      -- <li><a href="../modules/odbc.ex.Connection.html#Class_Connection">odbc.ex.Connection.Connection</a> </li>
-- - @{odbc.ex.Connection.Connection}  -- <li><a href="../modules/odbc.ex.Connection.html#Class_Connection">odbc.ex.Connection.Connection</a></li>
...

Connection and @{Connection} produce different links

Hi.

On updating, a few things seemed to blow up on me with colons (having updated to try out the colon syntax 😄).

In a case like

https://github.com/ggcrunchy/corona-sdk-snippets/blob/master/dot/Warp.lua#L159

everything is okay, but

https://github.com/ggcrunchy/corona-sdk-snippets/blob/master/dot/Warp.lua#L204

complains with something like "unknown tag: method nil". Cases of the former have "@" tags, and the rest don't, so I'm guessing that gets "method:" disambiguated (on purpose?).

This is showing up with file summaries, too.

Is this expected behavior? I had thought tags only showed up on the first word, apart from special forms like "@{STUFF}". Anyhow, liberal sprinkling of "&# 58;", for now...

Less bothersome, but in case these matter, the update flagged these down:

An otherwise-empty "---" and "----------------------" both error out. If the first case is the file summary, the error seems to misdirect you to a lower line. One instance of "---" was within a long comment too; not sure if that's expected.

When a function has a long prototype the function list in the generated API doc looks ugly, because the "summary" columns is forcibly shrunk too much, since the function name column cannot wrap.

To avoid this I suggest to remove the nowrap attribute from the "name" column (line #91 of ldoc.ltp). This way both columns can wrap.

I admit it is not nice to see the prototype wrapped, but it is better than see a column which is 4+ times wider than the other.

I tried to pass multiple local human-written markdown files in this config: https://github.com/vance-group/vr-jugglua/blob/master/doc/generation/config.ld

None of them appear in the output, and no error appeared during generation.

The following doc comment:

/// Implements a simple sound which has no
// stereo left/right panning or room positioning features.
// This is the sound object suited best for background music.
// It deactivates some postprocessing which allows positioning
// or stereo panning which results in slightly better and
// unaltered sound.
// @type simpleSound

.. will result in the following documentation output:

<h2><a name="Class_Thread"></a>Class Thread</h2>
This is the sound object suited best for background music.
It deactivates some postprocessing which allows positioning
or stereo panning which results in slightly better and
unaltered sound.

The first sentence is always omitted. This is even the case in the winapi docs. What's the rationale behind this? And what would I need to do if I wanted the first sentence to show up aswell?

The three lines above the "Installation" heading, there's commments instead of comments.

I have a licence comment at the top of ever file (actually two comments) and LDoc complains that the first comment isn't an LDoc comment. Is there any way to fix this as I would like to keep the licence at the top of every file.

I wouldn't mind slightly changing the comment so that it doesn't look like an LDoc comment by I was wondering the reason for this restriction.

At the moment, this doc comment:

/// Implements a simple sound which has no
// stereo left/right panning or room positioning features.
// This is t/// Implements a simple sound which has no
// stereo left/right panning or room positioning features.
// This is the sound object suited best for background music.
// It deactivates some of the postprocessing which would allow positioning
// or stereo panning which results in slightly better and
// unaltered sound.
// 
// The default @{blitwizard.audio.simpleSound:setPriority|sound priority}
// for simple sound objects is 5.he sound object suited best for background music.
// It deactivates some of the postprocessing which would allow positioning
// or stereo panning which results in slightly better and
// unaltered sound.
// 
// The default @{blitwizard.audio.simpleSound:setPriority|sound priority}
// for simple sound objects is 5.

.. becomes this wall of text:

"Implements a simple sound which has no stereo left/right panning or room positioning features. This is the sound object suited best for background music. It deactivates some of the postprocessing which would allow positioning or stereo panning which results in slightly better and unaltered sound. The default sound priority for simple sound objects is 5."

I would suggest honoring completely empty lines as either line breaks, or even better, actual new paragraphs, so the output would rather look like this:

"Implements a simple sound which has no stereo left/right panning or room positioning features. This is the sound object suited best for background music. It deactivates some of the postprocessing which would allow positioning or stereo panning which results in slightly better and unaltered sound.

The default sound priority for simple sound objects is 5."

For example, I get:

$ ldoc .
reading configuration from config.ld
adding ^(%a+)%((%d)$ function: 0xbdbd40
/home/rrt/Software/Lua/luaposix/lposix.c:2293: ?: 'name' cannot have multiple values

This is fine, but the line number is entirely bogus. I'm using "/*** ... */" style comments in a normal Unix-line-ending .c file.

There's a minor bug in ldoc.lua that prevents it from working if you have your own css file but not a custom template (or vice-versa).

The code that writes them to /tmp/ldoc has them flipped around. Here's a diff:

+++ /home/rosenqui/src/TrendMicro/DsPostFuji/dsa/docs/ldoc.lua  2012-11-26 17:48:45.000000000 0800
@@ -560,11 +560,11 @@
       utils.writefile(path.join(tmpdir,name),require('ldoc.html.'..name:gsub('%.','_')))
    end
    if args.style == '!' then
-      tmpwrite(ldoc.templ)
+      tmpwrite(ldoc.css)
       args.style = tmpdir
    end
    if args.template == '!' then
-      tmpwrite(ldoc.css)
+      tmpwrite(ldoc.templ)
       args.template = tmpdir
    end

Consider:

--- Does something.
--  First paragraph about that.
--
--  Second paragraph about that.
function a(b) end

With text markup LDoc will display this as one paragraph. If we're using markdown the user probably intended to have two paragraphs. The pattern in markup.markdown_processor will remove the first

and the last

At line #84:

Simularly --> Similarly

My tables as well as the simple one in tests/simple/tables.lua only show the table name and description.

Fields annotated using the simplified notation aren't recognized - explicit use of @field still works however.

The following comment:

--- It foos bar and baz.
-- param: bar Give it bar.
-- param: baz Give it baz.
-- This value should be special in some way.
function foo(bar, baz)
  ...
end

When generated, looks like:

<dd>
    It foos bar and baz.
 This value should be special in some way.

    <h3>Parameters:</h3>
    <ul>
      <li><span class="parameter">bar</span>
       Give it bar.</li>
      <li><span class="parameter">baz</span>
       Give it baz.</li>
    </ul>
</dd>

This only seems to occur on the last parameter. Using an explicit type (i.e. string: baz ...) prevents the behavior, but obviously, not all final parameters are going to be expected to be a specific type. I see the same behavior using @param as I do when using param:.

First of all, let me say that this is indeed a very handy tool.
I am using LDoc to generate documentation for a utility-belt library of mine, Moses.

I have some suggestions, though. Would it be possible to add support for optional args to a function ? I would love to have a syntax like this in the generated docs:

function foo(a, b [,c])

Besides this, I am using a standard version of LDoc, wihtout any custom changes. I just customised the config.ld file. I noticed that HTML references to the Lua Ref Manual are automatically added for string and table types. How can I add my custom ones ? For functions, numbers, and so on ?

Thanks in advance

Hi Steve,

Feature request...I don't know if (syntactically speaking) there's already a convention style in Lua for this, but I wish LDoc can feature default values for optional parameters to function.
Instead of writing something like this:

 ----
 -- slice like a ninja
 -- @param item the item
 -- @param[opt] weapon the weapon. Defaults to `katana` when not given
 funtion slice(item, weapon) .. end

Is it possible to have a syntax to specify weapon defaults to katana when omitted...?
That would be very handy, to me. And it could render like this in the HTML output:

function splice(item [,weapon=katana])

Well that's just a suggestion, I let you be judge.

Best regards,
Roland Y.

Same as for classes, but for tables too :) I have a complicated table (really complicated: http://www.blitwizard.de/doc-files/modules/blitwizard.html#object:shape_info ) and I'd like to add usage info directly to the table description.

This code fire error

---
-- @module test

--- Do work
-- @local
--
function some_function() end

f:\tmp\test.lua:7: internal LDoc error
G:\lua\5.1\libs\ldoc\lua\ldoc\doc.lua:382: attempt to concatenate local 'rest' (a boolean value)
stack traceback:
    G:\lua\5.1\libs\ldoc\lua\ldoc\doc.lua:382: in function 'add_to_description'
    G:\lua\5.1\libs\ldoc\lua\ldoc\doc.lua:415: in function 'set_tag'
    G:\lua\5.1\libs\ldoc\lua\ldoc\doc.lua:376: in function '_init'
    G:\lua\5.1\libs\penlight\lua\pl\class.lua:27: in function 'call_ctor'
    G:\lua\5.1\libs\penlight\lua\pl\class.lua:93: in function 'Item'
    G:\lua\5.1\libs\ldoc\lua\ldoc\doc.lua:150: in function 'new_item'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:321: in function <G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:220>
    [C]: in function 'xpcall'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:220: in function 'parse_file'
    G:\lua\5.1\libs\ldoc\lua\ldoc\parse.lua:342: in function 'file'
    G:\lua\5.1\libs\ldoc\utils\ldoc.lua:338: in function 'process_file'
    G:\lua\5.1\libs\ldoc\utils\ldoc.lua:390: in main chunk

Output for this example isn't what I expect (best you try it)

--- module test

--- Test Ldoc
function f(
  arg1, -- an argument
  arg2) -- a heated argument

end

For more fun, I'm putting annotations on arguments like the following, and it'd be great if the documentation tools and the parameter checker read the same language:

--- module test

--- Test Ldoc
function f(
  arg1, -- string: an argument
  arg2) -- 1..5: a heated argument

end

In my case, I have access (introspectively) to a variety of documentation. Right now, I'm writing out "fake" luadoc input files like those included for the Lua standard library, but given http://stevedonovan.github.com/ldoc/topics/doc.md.html#Internal_Data_Representation it seems like it would be smoother to pass data in process, as well as be able to pass a serialized table dump as input instead of/in addition to lua and c files to parse.