doc strings

[MadcapJake]

Support functions having a doc string immediately following their definition. e.g.,

func = x ->
   """
   This function adds a number to itself
   """
   x + x

func.doc-string() ;; => "This function adds a number to itself"

This could be utilized in editor tooling and in the repl.

[davej]

Is there a reason to make it a function call? As opposed to just func.doc-string?

[MadcapJake]

No, you're right. Also do you think it should be __doc__ like python?

[davej]

I don't know really, I don't think there's any precedence for marking 'magic' properties in Earl Grey. I don't particularly like the aesthetics of dunder variables but they should probably be marked somehow so they are distinguishable from normal properties.

[MadcapJake]

Functions currently have these:

__defineGetter__ 
__defineSetter__
__lookupGetter__ 
__lookupSetter__
__proto__

So I think the precedent is there.

[davej]

But they are javascript properties and not Earl Grey specific.

[MadcapJake]

Yeah, but maybe since docs would only be used in tooling, this might be a time to use the dunder style. I honestly don't mind either way how it's named though, just thought it might be a valid situation for that naming scheme.

[breuleux]

With Symbol, there is no reason to have magic properties that are strings. The documention could be accessed as fn[Symbol.doc], for example. To make it easier, a builtin help(fn) or doc(fn) function could be added.

[davej]

If there was a designated format for these docstrings. Then you could probably even parse the types for argument and return values and write out some typescript.

(Perhaps I've drank too much coffee)

[breuleux]

I'd rather not parse types from docstrings. I'd rather have something like [-> String?] fn(String? x, String? y) = ..., or maybe

typeof fn = {String?, String?} -> String?
fn(x, y) = ...

[MadcapJake]

That's be really cool!

But also as far as docstrings, leaving them without a format means that one could use JSDoc format, markdown, 💡 EGDoc(Quaint-based perhaps?), bare text, or something else!