Add doc-fn/help-fn

[terlar]

Not really a jump thing, but figured it could fit nicely in there, this would add a function for documentation lookup, help for the current keyword. In vim/evil mode it is bound to K.

Currently I setup the doc-fn to helpful-at-point in emacs-mode. I am not sure which name is better, either doc-fn or help-fn.

Thank you for this package, this is just something I have been thinking about configuring lately and this package will help greatly.

[jojojames]

I was thinking about it too as I migrate some of my settings to smart-jump-register.

  (smart-jump-register :modes 'java-mode
                       :jump-fn 'ggtags-find-tag-dwim
                       :pop-fn 'ggtags-prev-mark
                       :refs-fn 'ggtags-find-reference
                       :should-jump t
                       :heuristic 'point
                       :async 700)

  (with-eval-after-load 'evil
    (evil-define-key 'normal java-mode-map
      (kbd "K") 'javadoc-lookup
      (kbd "gf") 'ggtags-find-file))

  (smart-jump-register :modes 'csharp-mode
                       :jump-fn 'omnisharp-go-to-definition
                       :pop-fn 'pop-tag-mark
                       :refs-fn 'omnisharp-find-usages
                       :should-jump t
                       :heuristic 'point
                       :async 500)

  (evil-define-key 'normal csharp-mode-map
    (kbd "K") 'omnisharp-current-type-information)

The K and gf ends up being left out.

There's probably a couple commands that would be better generalized. I think I won't support 'gf'/find file at point but the doc function seems interesting.

I'll have to think about it a little before I do it, I kind of wanted to map 1:1 conceptually with xref (as well as dumb-jump) and adding doc seems to be out of that mapping.

I'm probably 80% for it though. 👍

[jojojames]

Is there a default help command for emacs? Something that matches evil's ~evil-lookup?

Also, are you planning on using this from a fallback point of view or just want a convenient place to add the 'K' mapping too?

[terlar]

What might be the most suitable as a default I guess would be man, it seems evil's evil-lookup is defaulting to woman. When it comes to emacs-lisp-mode I guess binding it to describe symbol could make sense.

I am using it from both fallback point of view and a convenient place to add the K mapping.

My current setup is to use source-peek as the fallback method, as that by itself provides fall-backs for most languages. It is not really documentation lookup per se, but something I found useful. I have been considering using something like dash-at-point for fallback, which handles multiple languages. Then I override for each language that has something that makes more sense.

mode	fn
emacs-lisp-mode	helpful-at-point
python-mode	pydoc-at-point
java-mode	javadoc-lookup
rust-mode	racer-describe
go-mode	godoc-at-point
enh-ruby-mode	robe-doc
elm-mode	elm-oracle-doc-at-point
fish-mode	man
sh-mode	man
ensime-mode	ensime-show-doc-for-symbol-at-point
ansible	ansible-doc-at-point
salt-mode	salt-mode-browse-doc
erlang-mode	erlang-man-function
lua-mode	lua-search-documentation
lisp-mode	slime-describe-symbol
haskell-mode	intero-info
alchemist-mode	alchemist-help-search-at-point

[jacktasia]

FWIW I think it might make sense to make what you're describing as its own package (something like smart-docs maybe). I wonder if there is any pattern(s) in smart-jump that can be made more abstract and used as a dependency (like a smart-x) for both? I think there are a few advantages to this approach. I'd be happy to go into detail on it if you guys agree it may make sense. 😄

[jojojames]

One thing I do like about adding the doc: key is that it puts alot of configuration into one place and makes it easier to manage.

Most of those help commands comes from the same packages that supply the M-., M-,, M-? commands so it feels relatively natural to add them.

I'm not sure how doc functions usually fail though. @terlar Do you think catching on the 'point' is a good enough heuristic to check for doc function failures? I'm guessing maybe not since the point might not move when a documentation window pops up.

Also, nice compilation of those commands!

@jacktasia I'd be curious about those details but also what you think the advantages are of one approach vs the other (merging vs splitting the package functionality).

[jacktasia]

@jojojames This is obviously pretty subjective and I totally agree there's a case for combining them. I am supportive of any route you guys want to take, but since you asked my subjective thinking is mainly:

1. Keep packages as simple as possible (KISS) there's already going to be fair amount (maybe lots) of complexity as this package builds out to support more languages
2. It's easier to find (and understand) packages that have one core objective.
3. In the long run it will probably lead to faster development and more contributors (potential comment you may [never] hear "I was going to add X jump feature but then I was confused how this fit into the doc sides). (related to above).
4. smart- could be similar to helm- (packages would just inherit the smart-x base package) and could become a family of packages that intelligently do something based on the language (jump to definition, find docs, etc.)

That's basically it. That said, if you guys decide to combine instead I think it would be neat to have an optional init func (like smart-jump-load-sane-default-registers or something) that would load all/some of the ones you outlined here and the impressive doc list @terlar made above so people could immediately be up and running in all/most languages...but I am admittedly obsessed with zero configuration software.

Happy to expand on anything if you guys want. 😄

[jojojames]

@jacktasia I agree with all of your points. I'm thinking, initially we might want to combine the patterns into one and once we see a pattern emerge, we can think about splitting them up (since the core logic at this point is relatively simple).

As for:

That's basically it. That said, if you guys decide to combine instead I think it would be neat to have an optional init func (like smart-jump-load-sane-default-registers or something) that would load all/some of the ones you outlined here and the impressive doc list @terlar made above so people could immediately be up and running in all/most languages...but I am admittedly obsessed with zero configuration software.

I completely agree and was thinking about adding something like that soon.

but I am admittedly obsessed with zero configuration software.

Definitely can empathize with that.

[jacktasia]

initially we might want to combine the patterns into one and once we see a pattern emerge, we can think about splitting them up (since the core logic at this point is relatively simple).

Cool, that makes a lot of sense to me.

[terlar]

@jacktasia I think those are good ideas, if a package could provide nice defaults so you just can just plug it in that would be really neat. But since it makes many assumptions it is important that it is customizeable and most important provide the functionality/platform to create configuration.

Related to that note I have been thinking about something to configure "language" specific things, most people does it and this is just one of the things. Of course using use-package for the configuration isolation comes a long way, so it is more when it comes to fall-backs etc. The reason I mentioned help-fn was that I felt it is kind of similar and as stated by @jojojames is often provided by the same packages. Other things I have considered totally unrelated to this but for language configuration where everyone runs different things are REPLs and and send to REPL functions. I think the common denominator for this is that I want to have the same bindings regardless of major mode but have them adapt what is running according to mode and usually they have some common behavior/wrapping so it is not good enough to just rebind these keys to different functions for every mode.

@jojojames I also don't think doc functions fail and have fall-backs, but perhaps if there are some more generic tools like dash which searches through several sources that could act as a fallback, but I am a bit hesitant defaulting to tools that are external. Also what sets the help-fn shouldn't jump around, although that might be something that the users could choose, I think some users might prefer using the same window and jump while some others might prefer a popup window, or even inline.

[jojojames]

@terlar Have you seen https://github.com/jojojames/evil-collection by the way?

Even if help-fn isn't added to this, I'm thinking most modes will bind the 'K' key to those commands you listed.

We could use your contributions there. :)

Also if you had any jumps you were using, I'd encourage you to submit them in the form of a pull request so I can merge it in with this repo.