Doc for functions

[Alex-Longard]

Hello all! please make inline documentation for functions (objects, built-in variables and others ...) in Soul commandline utility, for example how it works in Python. For example: soul help(audioin) soul help(namespace)

Thanks for you cool project!

[julianstorer]

OK.. that's a good FR, but would be a huge amount of work to restructure and manage our documentation in a database that could be used like that, and I'm not really sure if it's something that would be of interest to enough people to justify that (..?)

But it's an interesting idea - as we get further into the process of designing the way we'll handle soul library packages and their metadata, this is likely to become something that we'd consider.

Thanks!

[Alex-Longard]

Hello Julian, very big thanks in advance! I am the blind programmer and help in commandline very accessible and if you create functions for analize signal this more useful for reading... Thanks!

[julianstorer]

Ah! I can see why something like that would help you navigate the docs then. Thanks for the FR!

[Alex-Longard]

If you want, I can help you to quickly move the documentation to the console version, if you show an example of how it should be formatted.

[julianstorer]

Thanks for the offer. But first we'd need to have a serious think about exactly what format we'd use to manage the data, what kinds of tools we'd need to write to present and search it. It's not a trivial task! What might be helpful would be if you could post a few quick examples so we could look at them and ponder on what a good strategy might be..

[Alex-Longard]

O'k, i will write.

[Alex-Longard]

Hello Julian, For example in console:

[small example for command] ... For "help(...)" argument in console, example: soul help(float) >>> - `float` - fastest floating-point type that provides at least 32-bit precision >>> example: float variable_name = 0.12345; soul help(doc) [instructions, functions, structures, variables...] >>> basic types: float, int, bool... >>> functions: init(), run()... >>> namespaces: soul... ... soul help(soul::normaliseValue) >>> arguments: int i >>> return value: float >>> description: ... Sorry, i don't know Juce very well and can't write finished code, unless in pure C.

[julianstorer]

OK, thanks. We've been chatting about all the ins-and-outs involved in doing this. It's quite a chunk of work because we'd have to build some kind of database of this kind of language documentation, and also a system for annotating and parsing all the library code (which would probably mean writing our own parser like doxygen, for soul). Definitely all stuff we'd like to do, but probably will have to wait a while until we have more time/resources!

[Alex-Longard]

Hello Julian, o'k, thanks! I have not found actual documentation for libraries on soul.dev site. Now I'm analyzing the code and write a list of functions with arguments and return values.

[julianstorer]

FYI just to close-off this request, we have got a documentation generator now: https://soul-lang.github.io/SOUL/docs/soul_library.html

We'll be updating it with more features, a search, etc as time goes on.