Created attachment 23054 [details]
NetBeans Architecture Answers for Editor Hints module

As stated in the UI spec under Open Issues, I strongly agree that the module
should avoid using two icons and should instead find a way to be less intrusive
(for example, by replacing the 'x' annotation).  The current editor does not
support multiple annotations well, and adding yet another is likely to add to
the UI ugliness that usually results.

We agreed with Jan Rojcek, that the problem with annotations is more general -
there are several issues connected to that. It will be addressed in promoG/H.
Jan will file a new one-pager for that and create a new UI specification for
annotations where he will cover several use-cases including the editor hints
use-case.

That will be very helpful.  If you and Jan remember, please include
collaboration in the uses cases for annotations, as it makes heavy use of them also.

Y01 Performance: It is good that computation is done on background. However 
shall not there be "incremental" result delivery support as is in code 
completion api? Then you could show some hints before all of them get 
computed. Or does this contradict the UI usecases? 
 
Y02 Usage: It is not clear to me from the usecases who calls the 
HintsProvider.getHints(..., offset) and for which offset? 
 
Y03 Export: Please use friend dependencies between this api and the module 
that is going to consume it. Btw. which module is that in 4.2? Also describe 
that there is an exported api.  
 
Y04 APISupport: There is a huge problem in APISupport with resolution of 
unknown identifiers. The user types DialogDescriptor and would like the Hints 
or at least fix imports find that the class is from org-openide-awt.jar, add a 
dependency to it and correct import statement. What is the best way to 
implement this behaviour? 
 
Y05 ActionMapKeys are declared as imported API. Where it is imported from? Can 
you provide a link to document where it is announced? 
 

My view on Y03 (export):

I am against using friend stability level for this API. The editor hints API is
a general purpose API that should be used by modules in other clusters and
modules outside nb repository. It is not just a friend contract between two
modules. 

I would like to use this API in j2ee cluster in netbeans 4.2 if possible. It
would help us to resolve some usability issues. We currently have many important
actions in editor popup menu, e.g. "Call EJB", "Add Method To Local Interface",
etc. and moving them into completion (the former example) and hints (the later
example) will make them much easier to find.

Please use under developement if you are not comfortable with stable. I am OK
with stabilizing the API in the next release and making minor changes if needed.

> Please use under developement if you are not comfortable with stable. I am OK
> with stabilizing the API in the next release and making minor changes if needed.

We think the API may need significant changes, in the light of a rework of the
editor annotations and other stuff we discussed with Jan Rojcek and that will
happen after 4.2. That's why the original plan was to not provide any API at
all. During the planning meetings (phase 1) there were no requirements from
other teams on the hints module. We decided to invest our time and effort to
take this module and put it into the release since we did want to have Java
hints in 4.2 - we had a one-pager for that. No other modules proposed any hints
during planning, so as we saw it, the only module that needs the hints
infrastructure in 4.2 is java. So, no API needs to be exposed in 4.2 and using
implementation dependency for our purpose is fine. The project is staffed
according to these assumptions.

If the API as it is now is not the one that we will be able to use and if you
have no commitment to work on the API (you only plan to implement the feature)
then I can only say: (1) it is unfortunate, (2) I see no point is doing any review. 
Use friend API then. 

I am requesting a public API for editor hints in the next release (or ASAP) in a
form that we can actually use. Then we should do a review.

Re. Y04 (apisupport) - this is only one possible approach; for another, not
using the Hints SPI and probably better, see issue #60853. So I would not assume
this is a requirement.

Re. public vs. friend stability - it would certainly be nice to have
editor/hints be a real SPI! I'll take your word for it that changes are needed
to deal with annotation problems, but just a note: Tim B. and I managed to write
a functional hint provider for Ant scripts in about twenty minutes. However we
noted that making a useful hint provider that would work in Java sources could
be rather more complicated, and java/hints provided no SPI.

Y02: IMO, the editor/hints infrastructure (HintsOperator in particular) calls
this method in order to obtain the list of hints for the particular
position in the component. The offset is usually the current offset of the caret. 

Y04: I agree with Jesse: using SPI described in issue #60583 is a better way to
implement this functionality (will need some code in java/hints, but it should
be straightforward).

Strongly agree with pbuzek.  JSE will want to use the hints feature while
editing other languages: BPEL, XML schema, WSDL, etc.  We are interested in a
public API/SPI for use by other modules ASAP.

to tfast: I agree that SPI/API for hints is definitely necessary and will be
very useful (i.e. has many potential clients). All I'm saying is that we will
not be able to provide a stable or nearly stable SPI/API for 4.2. We can provide
the current thing as a friend API. It may be changed in promoG once the
annotations are redesigned and a final UI specification for hints is created
(since some of the UI requirements for future releases may have impact on the
framework and the resulting SPI/API).
Again, our primary goal is to have at least hints for Java in 4.2. Having the
SPI is a nice to have thing for 4.2 given the requirements NB team gathered.

Blocking issues were fixed.

Opinions document is available here:
http://openide.netbeans.org/tutorial/reviews/opinions_60843.html