beanquery icon indicating copy to clipboard operation
beanquery copied to clipboard

Improve function help by grouping by function type

Open mlell opened this issue 3 weeks ago • 2 comments

As someone new to beancount, I found the function documentation really hard to navigate. The old help functions dumped everything on screen at once, which was overwhelming. While developing a BQL query, I found myself looking for functions to transform certain argument types, however I just had an alphabetical function list. (Re-open of #262)

What I changed:

Progressive disclosure:

  • help functions now shows just a category overview (takes ~10 lines instead of 100+) and explains custom object types
  • help functions amount shows only amount-related functions, same for date, position, atomic,...

Better function docs:

  • Added argument explanations to some functions (the old docs assumed you knew what arguments meant)
  • Example: grep(pattern, string) now explains "pattern" is a regex and "string" is input text
  • Examples on some types, e.g. Position is something like 10 HOOL {100.30 USD}

Technical implementation:

  • Query functions are grouped according to their first argument's type by _describe_function().
  • In addition, the decorators @function, @register and @aggregator take a group= argument to refine (e.g. for account names, which are strings)

The main benefit is you can find functions now much easier without scrolling through pages of text. When I started with beancount, I had no idea what functions were available or how to use them - I hope this makes it easier.

mlell avatar Nov 06 '25 08:11 mlell