Skip to content
This repository has been archived by the owner on Sep 9, 2020. It is now read-only.

Docstrings on variables in environments #177

Merged
merged 16 commits into from
Oct 31, 2018
Merged

Docstrings on variables in environments #177

merged 16 commits into from
Oct 31, 2018

Conversation

jameshaydon
Copy link
Contributor

@jameshaydon jameshaydon commented Oct 30, 2018

This PR adds:

  • Documentation strings to variables in environments. Each variable is optionally documented.
  • Utilities to document primitives, including a pandoc-markdown quasiquoter.
  • A 3-argument version of the def special form which takes a documentation object.
  • A doc! primfn which prints the docs.
  • An apropos! primfn which prints docs for all variables in scope.
  • Documentation strings to all the primitive functions.

Fixes #163.
Fixes #71.

[ ("print!", \case
[x] -> do
putStrS (renderPrettyDef x)
pure nil
xs -> throwErrorHere $ WrongNumberOfArgs "print!" 1 (length xs))

, ( "doc!"
, oneArg' "actual-doc" $ \case
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why actual-doc and not doc?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just when I was developping, I didn't want to conflict with document (which I thought was called doc). Will fix.

Copy link
Contributor

@jkarni jkarni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More coming

src/Radicle/Internal/Doc.hs Outdated Show resolved Hide resolved
src/Radicle/Internal/Doc.hs Outdated Show resolved Hide resolved
src/Radicle/Internal/Doc.hs Outdated Show resolved Hide resolved
src/Radicle/Internal/Doc.hs Outdated Show resolved Hide resolved
[ ("print!", \case
[x] -> do
putStrS (renderPrettyDef x)
pure nil
xs -> throwErrorHere $ WrongNumberOfArgs "print!" 1 (length xs))

, ( "doc!"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This isn't actually impure, right? Is the idea that documentation raises questions about referential transparency?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, it's as impure as print!.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(It print's a formatted text to output, rather than return a string.)

src/Radicle/Internal/Pretty.hs Outdated Show resolved Hide resolved
src/Radicle/Internal/PrimFns.hs Outdated Show resolved Hide resolved
@jameshaydon jameshaydon force-pushed the f/in-lang-doc branch 3 times, most recently from f75eed8 to 874e3c9 Compare October 31, 2018 12:17
@jameshaydon
Copy link
Contributor Author

@jkarni Replaced doc-objects with simple strings.

@jameshaydon jameshaydon force-pushed the f/in-lang-doc branch 2 times, most recently from 0ef6a15 to 6439651 Compare October 31, 2018 12:41
Copy link
Contributor

@jkarni jkarni left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Aside from suggestions, LGTM!

@jkarni
Copy link
Contributor

jkarni commented Oct 31, 2018

@jameshaydon can you update the PR description to reflect the new design?

jkarni and others added 2 commits October 31, 2018 14:43
Co-Authored-By: jameshaydon <james.haydon@gmail.com>
Co-Authored-By: jameshaydon <james.haydon@gmail.com>
@jameshaydon jameshaydon merged commit 7624b8e into master Oct 31, 2018
@jameshaydon jameshaydon changed the title [WIP/RFC] Documentation functionality Docstrings on variables in environments Oct 31, 2018
@jkarni jkarni deleted the f/in-lang-doc branch October 31, 2018 19:49
@jkarni jkarni restored the f/in-lang-doc branch October 31, 2018 19:58
@geigerzaehler geigerzaehler deleted the f/in-lang-doc branch January 18, 2019 14:38
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

2 participants