Show related vars in doc buffers

[bbatsov]

For a while I wanted to implement for our doc buffers the following functionality - when you lookup some symbol in its doc buffer you also see some links to other related symbols. Something pretty similar to See also in https://clojuredocs.org/clojure.core/map

This should be pretty simple to implement, but will require some manual work:

• we need to create a middleware returning the related symbols (it would basically operate on a map where symbols are keys and the values are lists of symbols)
• we need to populate the built-in map with some sensible defaults
• we need to provide some Elisp interface to modify this map
• we need to update the doc buffer's UI

@cskksc @sanjayl Perhaps one of you would be interested in tackling this? :-)

[ckoparkar]

@bbatsov I would like to take this up :-) 🚀

[bbatsov]

Deal! :-)

On Friday, 6 May 2016, Chaitanya Koparkar notifications@github.com wrote:

@bbatsov https://github.com/bbatsov I would like to take this up :-) 🚀

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#1736 (comment)

Best Regards,
Bozhidar Batsov

http://www.batsov.com

[sanjayl]

Let me know if I can help you out with any of the subtasks Chaitanya
On May 6, 2016 5:16 PM, "Chaitanya Koparkar" notifications@github.com
wrote:

@bbatsov https://github.com/bbatsov I would like to take this up :-) 🚀

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#1736 (comment)

[ckoparkar]

@sanjayl Will do :-)

[ckoparkar]

This is what I have so far.

we need to create a middleware returning the related symbols (it would basically operate on a map where symbols are keys and the values are lists of symbols)

I've covered the basics. Although I'm gonna look into making this ns aware. Because some symbols like replace, read-string, with-bindings are present in multiple namespaces.

we need to populate the built-in map with some sensible defaults

The clojuredocs repo provides its mongodb database which includes see also information. I've just extracted it into a edn file for now. It has the structure {:doseq [:doall :dorun :for :dotimes], ... Is it ok to use such a file as a permanent solution?

we need to update the doc buffer's UI

I've added the basic buttons. But, like emacs doc buffers, forward and back buttons would also work great here. I'm gonna look into this now.

we need to provide some Elisp interface to modify this map

Is is because we want the user defined namespaces to have this feature too ?

[bbatsov]

I've covered the basics. Although I'm gonna look into making this ns aware. Because some symbols like replace, read-string, with-bindings are present in multiple namespaces.

This should be easy. Guess we can show namespaces in the docs buffer only when the related symbols are in another namespace.

The clojuredocs repo provides its mongodb database which includes see also information. I've just extracted it into a edn file for now. It has the structure {:doseq [:doall :dorun :for :dotimes], ... Is it ok to use such a file as a permanent solution?

It's ok, but both the keys and the values should have namespaces as well.

I've added the basic buttons. But, like emacs doc buffers, forward and back buttons would also work great here. I'm gonna look into this now.

Yeah, it would be nice to have those buttons. This has been on my mind for a while.

Is is because we want the user defined namespaces to have this feature too ?

Yep.

[Malabarba]

It has the structure {:doseq [:doall :dorun :for :dotimes],

Why keywords instead of symbols?

[Malabarba]

we need to provide some Elisp interface to modify this map

Is is because we want the user defined namespaces to have this feature too ?

Personally, I don't think that's important. I don't see people using elisp to add documentation to their Clojure code.
If we want library authors to add "related functions" to their functions then we need a Clojure interface for it (such as a metadata key). But even then, they would probably just write it directly in the dicstring instead.

[bbatsov]

Yeah, this is not very important in general. But it'd be trivial to
implement. We can leave it out for now though. Some docstring parsing
generating related symbols might be more useful.

On Sunday, 8 May 2016, Artur Malabarba notifications@github.com wrote:

we need to provide some Elisp interface to modify this map

Is is because we want the user defined namespaces to have this feature too
?

Personally, I don't think that's important. I don't see people using elisp
to add documentation to their Clojure code.
If we want library authors to add "related functions" to their functions
then we need a Clojure interface for it (such as a metadata key). But even
then, they would probably just write it directly in the dicstring instead.

—
You are receiving this because you were mentioned.
Reply to this email directly or view it on GitHub
#1736 (comment)

Best Regards,
Bozhidar Batsov

http://www.batsov.com

[bbatsov]

Just to clarify - I think it'd be nice to see for any var mentions in the docstring of the things we're showing documentation for and generate some potential "see also" links for them.

[ckoparkar]

Why keywords instead of symbols?

@Malabarba I haven't actually done any comparisons between the two. Keywords seemed natural for a map lookup. Do you think symbols would be better ?

@bbatsov Yep, understood. It would be really cool to have that.

Ill submit a PR by tomorrow.

[Malabarba]

Keywords seemed natural for a map lookup. Do you think symbols would be better ?

IIUC, the client will not give you a keyword, and you want to display function names (not keywords) to the user.
So you're going to to be looking up symbols, aren't you?

I could see using either strings or symbols, but keywords don't really get you any benefit.
For instance, you'll have the symbol clojure.core/doseq and you'll want to know that it's related to clojure.core/doall. Using keywords would only force you to do an additional conversion on the way in and on the way out.

[ckoparkar]

@Malabarba Yep. You're right. I'll store them as strings. The middleware gets the input as a string.

[bbatsov]

Fixed by #1742.

[ckoparkar]

I've filed another ticket 1746 for the docstring parser and am gonna start working on it today.