Re: "Usage:" comment, I suppose the text editor would have to correctly
parse the below?

(define-syntax simple-define-syntax ; Usage: (simple-define-syntax (<macro>
<template> ...) <expansion>)
  (syntax-rules ()
    ((simple-define-syntax (<macro> <template> ...) <expansion>)
     (define-syntax <macro>
       (syntax-rules ()
         ((<macro> <template> ...) <expansion>))))))

  (delay #| Usage: (delay <expression>) - Delay execution of <expression>|#
  (delay-force (make-promise <expression>)))

  (define-stream ; Usage: (define-stream (<func> <args> ...) <body> ...) -
define a function that returns a stream, and may tail-call a function that
returns a stream
     (<func> <args> ....)
    <body> ...)
  (define <func> (stream-lambda (<args> ...) <body> ...)))

....or, I don't know, can you be more precise about the rules for where the
Usage: comment is placed?  Given a ; Usage: comment, where does it get
attached in the text form of the program?

Lisps allow new definitional forms, which themselves may have a different
syntax for indicating the symbol that is to be defined.  That said, a good
rule for where a ;Usage: comment ought to go might possibly be definable.


On Tue, Feb 21, 2017 at 10:49 AM, luke wallace <>

> I went to great pains to explain that what symbols mean would have to be
> explained by the symbol/function creator in a comment inside the
> symbol/function definition. The editor would pull the explanation from that
> comment. The comment would have some identifier, such as "Usage:" or
> "Tooltip:" to prefix the comment, so that the editor knew it was a special
> comment. Each function/symbol would have to be manually commented in this
> way before the editor knew about it - after all, we can't expect an editor
> to speak to humans in an understandable way about what a function does
> without telling it so - because if it could we probably wouldn't need human
> programmers any more.
Check out the vibrant tech community on one of the world's most
engaging tech sites,!
Readable-discuss mailing list

Reply via email to