Is this a bug?

[hickey]

I am trying to use Luadox and I am having an issue with the generated documents.

For example if I have the following definition:

--- @section API

--- Returns a JSON document with basic node configuration
--
-- @example
--   { "version": "meshchat_version",
--     "node": "node_name",
--     "zone": "meshchat_zone_name" }
function config()
    print("Content-type: application/json\r")
    print("\r")
    print(string.format([[{"version":"%s","node":"%s","zone":"%s"}]], app_version, node_name(), zone_name()))
end

The generated documentation in the summary looks like the following:

It seems no matter what I do I can not prevent the detailed documentation from being inserted into the summary. The details are fine in the full definition of the function, but not in the summary.

Is there something that I am doing wrong or something that I am not understanding from the documentation?

[hickey]

@jtackaberry Any thoughts or comments on the above?

[jtackaberry]

Sorry about the delay, @hickey. The main bug here is with the documentation: while I do mention the importance of the period with @section I failed to say this also applies to functions and fields. The solution to your problem is to put a period after "configuration" so LuaDox knows this terminates the first paragraph, which is included in the table (unless @compact is defined on the section, in which case it includes all content in the table).

But I do also agree this violates the Principle of Least Astonishment. I think @example/@code should implicitly terminate the paragraph for this purpose. So from that perspective, even though it's working as intended, my original intention could stand to see some refinement.

I'll improve this behavior, but meanwhile just terminating the description with a period will get you past this.

[hickey]

Ah!!! That will work for me. I suspect part of the problem might also be that I quickly scan the docs and started playing. Thank you for your input and resolving my issue.

[jtackaberry]

Enhanced first-sentence detection released in v1.3.0.