I was searching for something similar, but my final solution write a documented header for Doxygen to parse. Doxygen is quite forgiving about grammar rules such as missing return type for functions so I think it should work with most scripts by writing the document similar to c++ style.
//! Provides generic functions for table manipulation.
//! Given an array where all elements are strings or numbers, returns table[i]..sep..table[i+1] ... sep..table[j].
static concat (table [, sep [, i [, j]]]);
//! Inserts element value at position pos in table, shifting up other elements to open space, if necessary.
static insert (table, [pos,] value);
//! Returns the largest positive numerical index of the given table, or zero if the table has no positive numerical indices.
static maxn (table);
//! Removes from table the element at position pos, shifting down other elements to close the space, if necessary.
static remove (table [, pos]);
//!Sorts table elements in a given order, in-place, from table to table[n], where n is the length of the table.
static sort (table [, comp]);
I also use the generated XML for autocomplete in my script editor