cannot document module functions after class

[jjvbsag]

Take the following code (only ldoc comments, no lua code inside):

------------------------------
-- My example module
-- @module example

------------------------------
-- My example class
-- @type myclass

------------------------------
-- Method of my class
-- @function myclass:init
-- @tparam boolean reset
-- @treturn boolean success

------------------------------
-- My class factory
-- @function example.create
-- @tparam table parameters
-- @treturn myclass a class object

This is the reference generated

Module example My example module Class myclass myclass:init (reset) | Method of my class myclass:create (parameters) | My class factory

Observations: function create is related to myclass, but should be releted to example function create is detected as object method with :, not as static member with .

When I change the module to

------------------------------
-- My example module
-- @module example

------------------------------
-- My class factory
-- @function example.create
-- @tparam table parameters
-- @treturn myclass a class object

------------------------------
-- My example class
-- @type myclass

------------------------------
-- Method of my class
-- @function myclass:init
-- @tparam boolean reset
-- @treturn boolean success

I get the expected output

Module example My example module Functions create (parameters) | My class factory Class myclass myclass:init (reset) | Method of my class

But this makes the module much more complicated to write, because I somehow must forward the metatable created below @type myclass to function create, where it is not in scope yet.

:question: Is there any smart trick, how I can get the first version of ldoc comments to generate the expected second version of output :question:

[djomlastic]

I just started using LDoc and I've hit this bump. I'm sure you found a way around this issue, but hopefully it'll help others who land here while searching (like I did). Wiki page briefly mentions @section end, unfortunately no examples there or within tests.

------------------------------
-- My example module
-- @module example

------------------------------
-- My example class
-- @type myclass

------------------------------
-- Method of my class
-- @function myclass:init
-- @tparam boolean reset
-- @treturn boolean success

------------------------------
-- @section end

------------------------------
-- My class factory
-- @function example.create
-- @tparam table parameters
-- @treturn myclass a class object

This closes @type section and gets the parser back into @module section. Also, there is @within tag that can be used to put blocks into implicit sections. It's a similar issue, but it can't help here unless it can somehow be used for explicit sections. When it comes to methods being detected as object methods instead of static (foo:bar instead of foo.bar), there is @static tag which is undocumented on the Wiki page. It should be expected, a tool for creating documentation doesn't have the greatest documentation :smile:.

[alerque]

I think @djomlastic covers how to get your docs in a different order than your code.

The other half of this issue is a duplicate of #249 (and others).