search

ianfhunter / GNOLL

GNOLL is an efficient dice notation parser for multiple programming languages that supports a wide set of dice notation
https://www.ianhunter.ie/GNOLL/
GNU General Public License v3.0
39 stars 23 forks source link

Docs: More technical documentation #427

Closed steven-murray closed 1 year ago

steven-murray commented 1 year ago

There is not much technical documentation about how to use this library from the different languages. There is a single example for Python (and here, I would suggest adding roll to the main __init__.py so one can do from gnoll import roll rather than from gnoll.parser import roll), but there are no examples on how to use gnoll from C++, haskell, go etc.

In addition, the options that are available (in the Python case) are not documented (I printed the docstring from python and found that there were several options, eg. mock, mock_const, breakdown etc). I wasn't sure if these could be specified on the CLI, as there is no --help option.

ianfhunter commented 1 year ago

I would suggest adding roll to the main __init__.py so one can do from gnoll import roll rather than from gnoll.parser import roll),

100%, Thank you for calling this out. I had investigated how to do this before but misled myself (I was looking in the setup files). It was a lot easier to do than expected. This is now the way to access the functions and the documentation has been updated to reflect this.

[...] there are no examples on how to use gnoll from C++, haskell, go etc.

In addition, the options that are available (in the Python case) are not documented (I printed the docstring from python and found that there were several options, eg. mock, mock_const, breakdown etc). I wasn't sure if these could be specified on the CLI, as there is no --help option.

I'm not sure it's entirely what you are looking for but I've expanded the per-language documentation, paying particular attention to any major differences between their foreign function interface setups.

The languages should all be using the same roll_full_options function, so I made an explicit section describing it and its inputs and outputs.

Please do let me know if if there is other improvements I can do to enhance this section! The only remaining content I could think to add would be effectively repeating the FFI sections of the languages' own documentation, which I would likely do less justice and fail to keep up-to-date with best practices.

I have added an issue to implement commandline flags for enabling/disabling the different features you mention

steven-murray commented 1 year ago

The added documentation is at the right level, I think. It should be relatively easy for someone familiar with a particular language to bind gnoll just by looking at the example given.