Suggestion: docstrings #540

New issue

2020-06-05T20:14:37Z

statianzo commented

2020-06-05 20:14:37 +00:00

(Migrated from github.com)

After asking about docstrings, @vyzo recommended opening an issue to encapsulate discussion.

There was previous discussion about it in gitter on May 26th.

Some points brought up were around:

Docstrings can discourage reading the actual code
Should reference docs be generated from docstrings?
(describe proc) would be an ideal interface

My scenario

As a very new Gerbil/Scheme user, I wanted to check out its testing facilities. I came across the documentation for :std/test.

Everything within the module is noted Please document me!.

Given that, I thought I'd just drop something in the repl to see what would happen.

10> (run-tests!)
*** ERROR IN (console)@23.1 -- Wrong number of arguments passed to procedure
(std/test#run-tests!)

I then tried out (doc run-tests!) and some variants to see the shape of the code (maybe argument names?). No luck. Having written some Clojure and Janet in the past, I figured I was missing a keyword or something.

So I went to gitter to ask.

Thoughts on where gerbil should head?

After [asking about docstrings](https://gitter.im/gerbil-scheme/community?at=5eda9d203ffa6106f1f8ebd2), @vyzo recommended opening an issue to encapsulate discussion. There was [previous discussion](https://gitter.im/gerbil-scheme/community?at=5ecd3814778fad0b13292792) about it in gitter on May 26th. Some points brought up were around: * Docstrings can discourage reading the actual code * Should reference docs be generated from docstrings? * `(describe proc)` would be an ideal interface ## My scenario As a very new Gerbil/Scheme user, I wanted to check out its testing facilities. I came across the [documentation for :std/test](https://cons.io/reference/test.html#testing). Everything within the module is noted *Please document me!*. Given that, I thought I'd just drop something in the repl to see what would happen. ``` 10> (run-tests!) *** ERROR IN (console)@23.1 -- Wrong number of arguments passed to procedure (std/test#run-tests!) ``` I then tried out `(doc run-tests!)` and some variants to see the shape of the code (maybe argument names?). No luck. Having written some Clojure and Janet in the past, I figured I was missing a keyword or something. So I went to gitter to ask. --- Thoughts on where gerbil should head?

👍 1

vyzo commented

2020-06-05 20:29:05 +00:00

(Migrated from github.com)

I agree that describe is an ideal interface for accessing documentation, perhaps after an import; this can be performed automatically by :std/interactive so that you always get it when you run an interactive gxi shell.

I have been thinking quite a bit about this issue, and I think it's best to generate the documentation from the doc folder. This can be done as part of the build, we could parse the markdown files and extract an index which can then be referenced by code in the stdlib.

Also note that the stdlib is (by default) compiled with debug symbols, so that you can do (pp some-stdlib-procedure) and get the actual (expanded) code of the procedure.

I agree that `describe` is an ideal interface for accessing documentation, perhaps after an import; this can be performed automatically by `:std/interactive` so that you always get it when you run an interactive gxi shell. I have been thinking quite a bit about this issue, and I think it's best to generate the documentation from the `doc` folder. This can be done as part of the build, we could parse the markdown files and extract an index which can then be referenced by code in the stdlib. Also note that the stdlib is (by default) compiled with debug symbols, so that you can do `(pp some-stdlib-procedure)` and get the actual (expanded) code of the procedure.

NightMachinery commented

2021-05-14 17:03:02 +00:00

(Migrated from github.com)

@vyzo I followed https://www.logc.net/posts/gerbil-development/ , and I don't have anything except syntax highlighting and send-to-REPL setup on my Emacs. No documentation, no go-to-definition, no auto-completion. Is my config wrong, or is it just what gerbil offers right now?

Update: After doing (visit-tags-table "/usr/local/Cellar/gerbil-scheme/0.16/share/gerbil/TAGS") and using company-etags, my auto-complete works, though I still need to manually generate tags for my own code.

@vyzo I followed https://www.logc.net/posts/gerbil-development/ , and I don't have anything except syntax highlighting and send-to-REPL setup on my Emacs. No documentation, no go-to-definition, no auto-completion. Is my config wrong, or is it just what gerbil offers right now? Update: After doing `(visit-tags-table "/usr/local/Cellar/gerbil-scheme/0.16/share/gerbil/TAGS")` and using `company-etags`, my auto-complete works, though I still need to manually generate tags for my own code.

vyzo commented

2023-09-09 13:57:23 +00:00

(Migrated from github.com)

See #803

Sign in to join this conversation.