consistent docstring format and language #1
Description
The reference generated from docstrings in lib/ needs a consistent format and language that helps to understand the individual ops clearly. The following bits of information need to be covered in every description:
- what does this op do?
- how should it be used? (give an example)
- which arguments does this op expect?
- what types do the arguments have to be?
- how does this op react to incoming messages? (value, event, cold inputs?)
- do any arguments have to be eval-time const?
- what type will this op return?
- does this op relate to other ops? (name them)
The docstring format should support some kind of rich styling (possibly the markdown extension that is already used to generate other doc pages), so that parameter names, example code etc. can be highlighted properly.