Jesse, this issue is on my TODO list. I will try to fix it till the 
end of this week - the chapter or two in Text package documentation 
must be rewritten as well. 

In case you filed this issue because you need to use Line.markError 
and just don't know how, let me know and I will assist (it is quite 
easy).

Created attachment 2253 [details]
two_new_chapters_into_text_package_documentation

Created attachment 2255 [details]
two_new_chapters_into_text_package_documentation - once more now from the path without spaces in the name

Jesse,

I attached to this issue proposal for two new chapters into Text 
package documentation (download second attachment). They will replace 
current chapters "Using IDE special attributes" and "Handling IDE 
special attributes" in text package documentation. I would like to ask 
you (if you have a time of course) to read it and let me know if there 
are answers for all your questions and if it is what you 
required. Comments/criticism are welcome.

David

OK, I will look at what you have and try to merge it into the Editor
API documentation. I can at least put in a first draft and either you
or I can revise it later if needed. Thanks!

OK and many thanx for your help. I feel that this is what I should 
do, but my English is not so good and APIs should be clear.

I read through the Editor API document and there are four places which 
have to be fixed. I already mentioned two chapters - these should be 
removed 
and replaced by the ones I have prepared. The remaing two parts are:
* Contents - the links to the deleted chapters should be updated
* Implementing a Custom Editor - "Be able to mark certain lines of the 
document..." should contain also some mention about glyph gutter 
icons. And a few lines 
below there is "or background colors for IDE markings" - this should 
be at least replaced by mention about annotations.

Just let me know in case I could help somehow...

The main thing I am missing is the answer to the original question: if
I have:

Line l = ...;
l.markError();

this is deprecated and what should it be replaced with? It seems you
need to get an "error" annotation from somewhere or other and
attach(l), but it is not at all obvious where the annotation comes
from. That is, the document is missing any helpful information for a
client of the API, it is focussed on the SPI (service provider).

What have changed is that there is no definition of errorline, 
breakpointline anymore. The modules which want to use new version of
l.markError()
must provide their own ErrorAnnotation which extends 
openide.text.Annotation and the ErrorAnnotation requires to define XML 
file which describes the visual appearance of the ErrorAnnotation.

So, your code:

Line l = ...;
l.markError();

must be replaced by:

Annotation errorAnno = new Annotation() {
  public abstract String getAnnotationType() {
    return "your_type";
  }

  public abstract String getShortDescription() {
    return "your_tooltip_text";
  }
}
Line l = ...;
errorAnno.attach(l)

// and the XML file for the "your_type" must be defined

Is this answer to your question?

Yes, I suppose so. It seems odd that every module providing error
lines would have to create a separate error annotation however; I can
think of offhand:

- org.openide.compilers.*

- Ant (hyperlinked errors in script output)

- apisupport layer parsing (XML syntax errors)

- probably any XML support module

Etc. These will all need to be separate annotation types? And the user
will need to e.g. configure colors for them all separately? ("Current"
and "breakpoint" are clearly debugger-specific but "error" is a pretty
general concept.) Given that, I would not be motivated to try to
replace the deprecated code!

Anyway this is enough for me to go on when documenting the API,
thanks.

OK, now documented in Editor API, please check it sometime for
accuracy.

Jesse,

I read the APIs and it looks good (and very nice with color syntex). 
Thank you very much for all improvements. I'm going to close this 
issue as verified.

To your previous question about using annotation for marking of 
errors. You are right, but I think the same approach should be applied 
as in debugger: 

There can be more implementation of debuggers. For example Java 
debugger, C++ debugger and they all share debuggercore module which 
contains definition of basic annotation types. 

So in case of compiler errors: I would also recommend to define some 
compiler error annotation type which all the compilers could share. 
Maybe the Compiler API is right place for this annotation type?

Resolved for 3.4.x or earlier, no new info since then -> closing.