References to submodules with backticks and @{tag}

[Yonaba]

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

[stevedonovan]

I think the latest push should sort out the issue. It came as a surprise to me, but @{mod} wasn't implemented properly! It was finding the module object and then didn't know how to turn it into a reference.

[Yonaba]

Actually, the latest push indeed fixed some odds. And that's perfect. Huge thanks for that.
Although the initial problem remains unsolved, but I do have the feeling I haven't stated my point incorrectly.
Here is an example.
In lib.lua, the description for lib.newLog function has a inlined reference (with backticks) to the module core.log, but the generated documentation won't convert that reference into an HTML link, but just wrap it into <code></code> tags.
Well replacing log with core.log produces the desired output, and that's normal, as the very name of the inner submodule is core.log. But keeping it as it is makes it easier to read, instead of writing:

--- Returns a `core.log` instance.
-- @treturn log a `core.log` instance
function lib.newLog() ... end

[alerque]

It is a little hard to tell since the MWE repository has been removed, but it seems to me that needing the fully qualified module name is expected. If the only remaining thing here is a request for a shortcut way of reaching submodules, I think I'm going to suggest that's not a great idea for long term maintainability. I would be too easy to get things cross-wired if the module was ever refactored and not notice the problem.

If there is something else I'm missing feel free to comment for re-evaluation. Alternatively if anybody has a PR they think is an improvement that doesn't break anything else I'd definitely consider the use case.