This Bugzilla instance is a read-only archive of historic NetBeans bug reports. To report a bug in NetBeans please follow the project's instructions for reporting issues.
UI spec. is available at: http://editor.netbeans.org/hints/editorhintsuispec.html
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