About definition finding

About definition finding

[Xue Fuqiao]

In (info "(elisp) Coding Conventions"):

    * Constructs that define a function or variable should be macros,
      not functions, and their names should start with `define-'.  The
      macro should receive the name to be defined as the first argument.
      That will help various tools find the definition automatically.
      Avoid constructing the names in the macro itself, since that would
      confuse these tools.

Which tools will make use of it?  Imenu/etags/...?  I'm not quite 
familiar with it.  Can anybody help?  Thanks.

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao

RE: About definition finding

[Drew Adams]

> In (info "(elisp) Coding Conventions"):
> 
>     * Constructs that define a function or variable should be macros,
>       not functions, and their names should start with `define-'.  The
>       macro should receive the name to be defined as the 
>       first argument.
>       That will help various tools find the definition automatically.
>       Avoid constructing the names in the macro itself, since 
>       that would confuse these tools.
> 
> Which tools will make use of it?  Imenu/etags/...?  I'm not quite 
> familiar with it.  Can anybody help?  Thanks.

Yes, both Imenu and Emacs tags.  And perhaps other tools that you might write to
take advantage of such a convention.

Note that this doc section's guideline conflicts a bit with that of adding a
package/library prefix to such macros.  E.g., `icicle-define-command' vs
`define-icicle-command'.  I put the library prefix first, but others might do
otherwise.

Re: About definition finding

[Xue Fuqiao]

On 03/07/2013 12:11 AM, Drew Adams wrote:
>> In (info "(elisp) Coding Conventions"):
>>
>>      * Constructs that define a function or variable should be macros,
>>        not functions, and their names should start with `define-'.  The
>>        macro should receive the name to be defined as the
>>        first argument.
>>        That will help various tools find the definition automatically.
>>        Avoid constructing the names in the macro itself, since
>>        that would confuse these tools.
>>
>> Which tools will make use of it?  Imenu/etags/...?  I'm not quite
>> familiar with it.  Can anybody help?  Thanks.
>
> Yes, both Imenu and Emacs tags.  And perhaps other tools that you might write to
> take advantage of such a convention.

Ah, I see, thanks.

> Note that this doc section's guideline conflicts a bit with that of adding a
> package/library prefix to such macros.  E.g., `icicle-define-command' vs
> `define-icicle-command'.  I put the library prefix first, but others might do
> otherwise.

Does alias make sense?  E.g., `package-list-packages' is an alias of 
`list-packages'.

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao

RE: About definition finding

[Drew Adams]

> > Note that this doc section's guideline conflicts a bit with 
> > that of adding a package/library prefix to such macros.  E.g., 
> > `icicle-define-command' vs `define-icicle-command'.  I put
> > the library prefix first, but others might do otherwise.
> 
> Does alias make sense?  E.g., `package-list-packages' is an alias of 
> `list-packages'.

First, note also that `list-packages' is a command, not a macro.  The aliasing
in that case is presumably for user convenience interactively.

Beyond that, someone from Emacs Dev can perhaps speak to the relation between
such a guideline and aliasing in general.

I would guess that if you bother to follow the guideline for a macro then there
is little sense in following that up by then defining an alias and using that
instead.

In principle, the guidelines are there to help you and those who use your code.
But remember that they are just guidelines, not rules to be followed blindly
without using your judgment.  Do what makes the most sense to you, after reading
the guidelines.

Re: About definition finding

[Xue Fuqiao]

On 03/07/2013 06:31 AM, Drew Adams wrote:
>>> Note that this doc section's guideline conflicts a bit with
>>> that of adding a package/library prefix to such macros.  E.g.,
>>> `icicle-define-command' vs `define-icicle-command'.  I put
>>> the library prefix first, but others might do otherwise.
>>
>> Does alias make sense?  E.g., `package-list-packages' is an alias of
>> `list-packages'.

> First, note also that `list-packages' is a command, not a macro.  The aliasing
> in that case is presumably for user convenience interactively.

Sorry, I forgot it.

[...]

> In principle, the guidelines are there to help you and those who use your code.
> But remember that they are just guidelines, not rules to be followed blindly
> without using your judgment.  Do what makes the most sense to you, after reading
> the guidelines.

That's true, especially for those in (info "(elisp) C Integer Types").

-- 
Best regards, Xue Fuqiao.
http://www.emacswiki.org/emacs/XueFuqiao

Re: About definition finding

[Michael Heerdegen]

Xue Fuqiao <xfq.free@gmail.com> writes:

> In (info "(elisp) Coding Conventions"):
>
>    * Constructs that define a function or variable should be macros,
>      not functions, and their names should start with `define-'.  The
>      macro should receive the name to be defined as the first argument.
>      That will help various tools find the definition automatically.
>      Avoid constructing the names in the macro itself, since that would
>      confuse these tools.
>
> Which tools will make use of it?  Imenu/etags/...?

Also `find-func.el' comes to my mind.

Michael.