Skip to content

Commit

Permalink
Default eldoc-documentation-function to nil
Browse files Browse the repository at this point in the history 
As opposed to racket-eldoc-function.

By volume, most of this commit is documentation explaining why.

Closes #181.
Closes #199.
  • Loading branch information
Greg Hendershott committed Jun 6, 2016
1 parent 392f306 commit 9738042
Show file tree
Hide file tree
Showing 3 changed files with 42 additions and 1 deletion.
21 changes: 21 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,27 @@ init file:
(require 'smartparens-config)
```

### eldoc

By default racket-mode sets `eldoc-documentation-function` to `nil` --
no `eldoc-mode` support. You may set it to `racket-eldoc-function` in
a `racket-mode-hook` if you really want to use `eldoc-mode` with
Racket. But it is not a very satisfying experience because Racket is
not a very "eldoc-friendly" language. Although racket-mode attempts
to discover argument lists, contracts, or types this doesn't work in
many common cases:

- Many Racket functions are defined in `#%kernel`. There's no easy way
to determine their argument lists. Most are not `provide`d with a
contract.

This comment has been minimized.

Sign in to view

Copy link
@cpitclaudel

cpitclaudel Mar 22, 2017

Contributor

Is there an existing racket bug report about this?

This comment has been minimized.

Sign in to view

Copy link
@greghendershott

greghendershott Mar 22, 2017 •
edited
Loading

Owner

I don't know that it's a Racket bug per se.

  • Most (all?) #%kernel functions are written in C. Maybe it would be possible to parse these but I'm not eager to volunteer to do that. :)
  • Most of these are not wrapped in a contract probably because racket/contract is not available in #%kernel. Besides, most predate contracts.

One interesting possibility: Try to parse, not the source code, but the Scribble documentation -- the argument lists in defproc forms.

This comment has been minimized.

Sign in to view

Copy link
@cpitclaudel

cpitclaudel Mar 22, 2017

Contributor

The last possibility sounds like a very good idea. Contracts not being available should be fine, but argument names would be very useful.

- Many of the interesting Racket forms are syntax (macros) not
functions. There's no easy way to determine their "argument
lists".

This comment has been minimized.

Sign in to view

Copy link
@cpitclaudel

cpitclaudel Mar 22, 2017

Contributor

Is there something that makes racket macros less eldoc-friendly than (say) ELisp or Clojure macros?

This comment has been minimized.

Sign in to view

Copy link
@greghendershott

greghendershott Mar 22, 2017 •
edited
Loading

Owner

If a macro is defined with define-syntax-rule, it would be comparable to defmacro and usualy fairly straightforward.

However many (most?) macros are defined with syntax-case. And there's syntax-parse, and its syntax classes. So ... yeah.

Also see my comment on issue 199: Although Racket may not be very "eldoc friendly", I think the flip side is that the overall documentation is much better and worth reading. Not to pick on Clojure, but much of its documentation is pretty much nothing but eldoc level: The arg names are supposed to be self-documenting, and there's maybe a sentence description.

Having said all that, I understand the idea that eldoc be a helpful hint, simply remind you if the args are foo bar or bar foo. And I wish it were simpler to support that for Racket.

This comment has been minimized.

Sign in to view

Copy link
@greghendershott

greghendershott Mar 22, 2017

Owner

Re macros see also comment on #209.

This comment has been minimized.

Sign in to view

Copy link
@cpitclaudel

cpitclaudel Mar 22, 2017

Contributor

Having said all that, I understand the idea that eldoc be a helpful hint, simply remind you if the args are foo bar or bar foo. And I wish it were simpler to support that for Racket.

Exactly: that's what I missed in Racket as a beginner. The documentation is definitely great, but I usually rely a lot on just argument names, and having them readily available is great.

A more satisfying experience is to use `racket-describe' or
`racket-doc'.

## Documentation

Within Emacs, use the usual help functions.
Expand Down
2 changes: 1 addition & 1 deletion racket-common.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -242,7 +242,7 @@ a list of all modes in which Racket is edited."
(racket--set-indentation)
(setq-local indent-tabs-mode nil)
(setq-local completion-at-point-functions (list #'racket-complete-at-point))
(setq-local eldoc-documentation-function #'racket-eldoc-function)
(setq-local eldoc-documentation-function nil)
(setq-local beginning-of-defun-function #'racket--beginning-of-defun-function))


Expand Down
20 changes: 20 additions & 0 deletions racket-complete.el
View file
Original file line number Diff line number Diff line change
Expand Up @@ -143,6 +143,26 @@ prompt uses READER, which must be a function like
;;; eldoc

(defun racket-eldoc-function ()
"A value suitable for the variable `eldoc-documentation-function'.
By default racket-mode sets `eldoc-documentation-function' to nil
-- no `eldoc-mode' support. You may set it to this function in a
`racket-mode-hook' if you really want to use `eldoc-mode' with
Racket. But it is not a very satisfying experience because Racket
is not a very \"eldoc friendly\" language. Although racket-mode
attempts to discover argument lists, contracts, or types this
doesn't work in many common cases:
- Many Racket functions are defined in #%kernel. There's no easy
way to determine their argument lists. Most are not provided
with a contract.
- Many of the interesting Racket forms are syntax (macros) not
functions. There's no easy way to determine their \"argument
lists\".
A more satisfying experience is to use `racket-describe' or
`racket-doc'."
(and (racket--repl-live-p)
(> (point) (point-min))
(save-excursion
Expand Down

0 comments on commit 9738042

Please sign in to comment.