[User Story] Writing / documenting Methods/Functions that use table arguments

[andrewstarks]

trafficstars

Often I write methods that use a table as an argument. Most often, it's the only table, but not always.

When I document this in LDoc, I have to make a separate notation that describes the message. This shows up under a Table heading at the bottom of the module.

Most often, this sucks. I'm passing these messages between modules and so they don't belong to a particular module. So, having them appear in only one of them is less than ideal.

Also, there are some rules for these messages (they must always contain a url and a command, for example), but certain methods have certain requirements. As it is, I have to make a brand new @table entry for each variant that rises to the level of importance, requiring me to document it.

The adhoc type definitions don't work either, because they only work as a sort of... opaque scribbling of what I sort-of-mean.

Here are some meager suggestions, that are meant to further convey what I'm trying to do:

--[[---
My method.
@tparam {
    url = string|url The url that is the target for this message.
    mc_type = ?string the Media type of the `mc_content` field.
    mc_content = ?any The content
} request
]]
function class:meth(request) ... end

The above format is not critical to the story. The above example would be greatly enhanced if I could somehow convey that what I want is some kind of referenced arg-table, but different... Perhaps something like:

@argtable request
@tparam string  mc_type The Media type of the `mc_content` field. Notice that this is mandatory!
@param[opt] mc_content The content of the message
} 

--[[---
My method.
@tparam @{request|{
    url = string|urlThe url that is the target for this message. Notice that I added this.
    mc_type = ?string the Media type of the `mc_content` field. Notice that I've over-written this field definition on this method.
} request
]]
function class:meth(request) ... end

Again, the specific format is not critical. In fact, I don't really like it. The outcome that I'm conveying is one that includes an ability to define an argument table, so that I can use it for multiple methods. In the second example I'm conveying that it'd be great to be able to use that template and override the field definitions, as needed.

As it is, table arguments are very difficult to document in LDoc.