70

Documenting code? : scheme

 6 years ago
source link: https://np.reddit.com/r/scheme/comments/7g267q/documenting_code/
Go to the source link to view the article. You can view the picture content, updated content and better typesetting reading experience. If the link is broken, please click the button below to view the snapshot at that time.
this post was submitted on 28 Nov 2017
9 points (84% upvoted)
shortlink:

scheme

joinleave6,617 readers

12 users here now

Scheme Programming Language articles.

Scheme is one of the lingua franca of programming language theory (PLT) so PLT articles are also welcome!

Also see:

Scheme implementations:

a community for 12 years



I've been writing a bit of elisp and using docstrings and looking things up with C-h f and C-h v has made coding so much more dynamic for me (coming from C++)

I was thinking about trying a Scheme to do things outside of the Emacs bubble, but (and I feel like I'm probably wrong about what I'm about to say..) there doesn't seem to be proper in-code documentation like in Elisp.

Racket has Scribble which seems like an kinda ugly org-mode haha. It's more S-expression-y (though I'm not sure what purpose that serves) and I'm sure it generates great HTML pages it but it doesn't binding a description to a function/variable like docstrings - . It's also rather ecosystem-y and tied to one language so I'd rather stick with org-mode for literate stuff I'm writing.. but maybe I'd miss some features that way?

Looking at the Racket code the in-code documentation are just sparse comments: https://github.com/racket/racket7/blob/master/racket/src/racket/src/mk-uchar.rkt

Chicken seems to have a bit more structure ex:

(define (rewrite-c-w-v db classargs cont callargs)
;; (call-with-values <var1> <var2>) -> (let ((k (lambda (r) (<var2> <k0> r)))) (<var1> k))
;; - if <var2> is a known lambda of a single argument
(and (= 2 (length callargs))

.. etc.

But the actual documentation I think is separately maintained in HTML. Is that just the workflow with Scheme? Code in one window and docs in the browser? Or can I recreate my elisp workflow somehow? And tangentially - Scribble v. Orgmode.. what's the advantage?

EDIT:

http://www.nongnu.org/geiser/geiser_3.html#Autodoc-and-friends

Looks like GNU Guile supports docstrings, while with Chicken/Racket you're stuck with having to use the HTML and only seeing the functions/variables/etc that come with the language


About Joyk


Aggregate valuable and interesting links.
Joyk means Joy of geeK