[Bro-Dev] [JIRA] (BIT-1107) Documentation of BIFs that take variable number of arguments

[Jon Siwek (JIRA)]

     [ https://bro-tracker.atlassian.net/browse/BIT-1107?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Jon Siwek updated BIT-1107:
---------------------------

    Description: 
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).

  was:
{quote}
md5_hash%(...%)  ===>  Type : function (va_args: any)
{quote}

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.

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

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.

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

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" ?


> Documentation of BIFs that take variable number of arguments
> ------------------------------------------------------------
>
>                 Key: BIT-1107
>                 URL: https://bro-tracker.atlassian.net/browse/BIT-1107
>             Project: Bro Issue Tracker
>          Issue Type: Problem
>          Components: Bro
>            Reporter: Daniel Thayer
>
> 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).



--
This message was sent by Atlassian JIRA
(v6.2-OD-03#6206)