Documentation about the completion framework

[Daniele Nicolodi <daniele@grinta.net>]

Hello,

I'm implementing completion-at-point for an emacs mode.

Unfortunately docstring of the relevant elisp functions are not always
detailed and in some cases not complete. I would also really appreciate
some documentation on how the framework can be used and how is it
supposed to be used, even better if there would be some hints on how to
keep it efficient.

Does such documentation exist somewhere? Does anyone have any resource
to recommend?

One specific question I have: in some circumstances completion-at-point
enters a mode in which it is called for each keystroke (I think this is
completion-in-region-mode). How does this happen and why? I would like
to avoid that my function to collect completion targets get called on
each keystroke. Is there a way to do that?

Another question: what is the most efficient way to collect completion
targets in the current buffer? Is there an alternative from doing it at
ache invocation of the completion-at-point hook?

Thank you!

Cheers,
Dan