Documentation of BIFs that take variable number of arguments


The function prototype for BIFs that take a variable number of
arguments appears in an altered form in the online documentation.

Here is a comparison of how these functions appear in the source code,
versus what they look like in the online documentation:

md5_hash%(...%) ===> Type : function (va_args: any)
order%(v: any, ...%) ===> Type : function (va_args: any)
sort%(v: any, ...%) ===> Type : function (va_args: any)
cat_sep%(sep: string, def: string, ...%) ===> Type : function (va_args: any)

The functions that have a named argument ("v" in sort, or "sep" in cat_sep)
have those arguments described in the online documentation, but we
cannot see them in the function prototype (only "va_args" is shown,
which isn't actually the name of any function argument).




Jon Siwek
December 7, 2013, 4:12 AM

(sorry, meant to comment, not edit the description)

md5_hash%(...%) ===> Type : function (va_args: any)

I'm thinking the only thing here would be to expect the documenter to know how the BIF compiler translates variadic functions and to add documentation for the va_args parameters. Otherwise the only thing I can think that might make it more clear would be to change the Bro parser to do variadic functions in a more familiar way.

order%(v: any, ...%) ===> Type : function (va_args: any)
sort%(v: any, ...%) ===> Type : function (va_args: any)

These look like a hack to workaround the BIF compiler's limitation of not being able to parse the full range of Bro types, in this case functions.

Ideal solution: fix it so full range of Bro types can be parsed in BIFs.

Workaround: just improve documentation about how a function with a param of type "any" can be used like a variadic function and for each hacky use of it, make it clear in the docs what the expected arguments are.

cat_sep%(sep: string, def: string, ...%) ===> Type : function (va_args: any)

I'm not sure what would fix this... maybe better variadic function support in Bro is needed so the BIF compiler will just pass the named arguments through instead of combining it into one "va_args: any" ?

Robin Sommer
December 7, 2013, 4:33 AM

The work-around of turning va_args function arguments into (...)}, along with a manual textual description of how the parameters are supposed to look like in each case, would sound good to me.

Btw, I believe this is how Bro recognizes va_args functions:

Would be nicer to have some more explicit way some time.




Daniel Thayer



External issue ID