Document what doc comments/docstrings are good for

[vks]

The documentation tells you how to create doc comments, but it is not clear what they are good for. Maybe give a hint at how to use them?

(use code documentation)
(print (documentation ...))

It might make sense to have a function help that prints the documentation, like in Python. It would not be terribly useful at the moment, because it seems that the built-in functions and operators don't have docstrings.

[murarth]

A help function is a good idea, but I'm not sure where it would go. I don't want to make it a built-in (i.e. Rust-implemented) function. The best option, I think, is to take a page from Python's book and have the Ketos REPL (and only the REPL) implicitly load some module, containing the help function. Unfortunately, an absolute location of libraries has not been established. I'm not sure if Cargo is equipped to install data files.

Documentation for built-in functions is also a good idea. One of those things I meant to get done at some point.

[murarth]

Also, I was kind of thinking of looking into whether rustdoc could accept a plugin or something to generate Rust-esque documentation from Ketos code. I'm not sure how plausible that idea is. This would be in addition to a help function for quick doc access in the REPL.

[vks]

You could put the modules into the ketos binary, using some build.rs magic. If you only store the bytecode and possibly compress it, it should not bloat the binary too much.

I think loading some modules by default in interactive mode is a great idea. list could be a good candidate for that as well.

[murarth]

I don't like the idea of building module files into the binary. It's a weird and surprising thing for a language interpreter to do.

Perhaps the best solution for now is to define your own help function in your RC file (another feature lacking in documentation -- oops).

[vks]

What about a KETOSPATH environment variable? Like Python is having.

[murarth]

That is implemented already. It's KETOS_PATH. https://github.com/murarth/ketos/blob/master/docs/README.md#environment-variables

[murarth]

As a start, I've pushed a commit that adds docstrings to system functions. So, there's that.