Table fields being parsed incorrectly

[wolfiestyle]

I'm trying to generate documentation for this, it's a long table declared in a module. I want to get a listing of all the module fields (table contents don't matter). A sample section looks like:

--- Test description.
_M.get_mentions = { GET, "statuses/mentions_timeline", {
        count = false,
        since_id = false,
        max_id = false,
        trim_user = false,
        contributor_details = false,
        include_entities = false,
    },
    "tweet_list"
}

But after adding the doc comment, I get wrong output:

get_mentions Test description. Fields:

• GET:
• statuses/mentions_timeline:
• {:
• since_id:
• max_id:
• trim_user:
• contributor_details:
• include_entities:

It seems to choke on the nested list/table.

[stevedonovan]

Yeah, currently it is only doing simple one-level tables. It's hard to parse general tables, and then we would have the tricky problem of how to present this.

Best thing to do for now is be explicit:

--- Test description.
-- @table get_mentions
-- @field count
-- @field since_id
-- @field max_id
-- @field trim_user
-- @field contributor_details
-- @field include_entities
....

You can of course put explicit type information like @int count etc.

[wolfiestyle]

Why not just eval the table as Lua code? Or just fallback to a module field when it can't properly parse a table. This way would prevent the wrong output.

[stevedonovan]

The first isn't an option, because it can be anything. I like your suggestion that ldoc should at least know when it's confused and put out an error, or warning plus plain module entry.

[vintprox]

--- Module defaults
-- @table Typewriter
Typewriter = {
    utf8 = false, -- whether to use shims in favor of strings containing Unicode characters
    Mission = {
        gear = nil, -- gear that is being focused by camera
        swh = false, -- whether to switch camera's position to gear during whole animation
        swh_after = true, -- whether to switch camera's position to gear after whole animation
        caption = " ", -- default caption for ShowMission
        subcaption = "", -- default subcaption for ShowMission
        text = "", -- default text for ShowMission
        icon = 10, -- default icon for ShowMission
        sound_typing = sndRopeRelease, -- sound that is played for typing
        sound_return = sndRopeAttach, -- sound that is played after whole animation is considered complete (after return delay)
        delay_caption_start = 600, -- delay before caption animation starts
        delay_caption_char = 100, -- typing delay for caption animation
        delay_subcaption_start = 200,-- delay before subcaption animation starts
        delay_subcaption_char = 100, -- typing delay for subcaption animation
        delay_text_start = 200,-- delay before text animation starts
        delay_text_char = 50, -- typing delay for text animation
        delay_return = 800, -- delay before whole animation is considered complete (return delay)
        display_time_after = 0, -- time for ShowMission after all animations end (concurrent to the return delay)
        force_display_after = false -- whether to forcedly display mission panel after all animations end
    }
}

LDoc doesn't seem to produce nested table structure in output, and gear here is being ate all of a sudden

EDIT: Solved by using explicit @field annotations