Re: tags for functions

[Ted Zlatanov]

On Thu, 29 Jan 2009 16:52:04 -0500 Stefan Monnier <address@hidden> wrote: 

>> Then Emacs will use it, for example, to show related functions in C-h f
>> The package can also provide browsing by keyword, as finder.el does.

SM> I see, thanks.  The list of related functions can be rather long, so
SM> it's probably better to only add a "show related" button in C-h f and
SM> only show the list when the user asks for it.

OK.

>> 2) scan existing docstrings over mapatoms using `documentation' (it's
>> slow now apparently, so it will need to be optimized for a batch scan)

SM> If it's only done "once per session" and only when the user specifically
SM> asks for this info, it's probably not that bad.

OK.

>> I only need defun-after-hook to be approved, I can do the rest.  Do you
>> agree it's useful or would you rather not provide such a hook?

SM> I'm not convinced.  I'm not even sure this kind of info will turn out to
SM> be useful/usable.  Currently, you'd spend all your time scanning
SM> docstrings that don't contain any such keywords.  

We have to start somewhere.  It's definitely useful to me, and two other
people that started the original thread.  The example that brought it up
is that motion functions are legion in the Emacs Lisp namespace, and
have wildly disparate names.  A "motion" tag would allow a curious
explorer to see what other motion commands exist from any starting
point.  I suggested some other tags.

SM> Adding those keywords to docstrings would be a major undertaking.
SM> So it's probably better to start with data from elsewhere (e.g. from
SM> the elisp manual) anyway.

Yes, but I'm sure it can be automated a bit regardless.  The hard part,
actually, is picking the right keywords as others have pointed out.

SM> In other words, maybe a defun-after-hook ill be the right tool, but
SM> we're pretty far from being in a position to judge, and it seems likely
SM> that the end design will use a completely different approach anyway.

Understood.  Rather than overengineer, I will provide a simple working
solution that uses docstring tags, gathering them all when it's first
loaded as a package (so autoloading will DTRT as you suggested).  If it
needs optimizations, they can be added later.

Ted