Re: TaskList API proposal

On Mon, 2002-10-28 at 06:37, Tim Lebedkov wrote:
> Hi Tor,
> 
> I've read the API.
> 1. Why don't we have SuggestionType as a class? It should be created so we
> can simply get description or icon for type of a suggestion.

It was an attempt to reduce the number of classes in the API, and
reduce the number of objects the user will create.

It wouldn't be sufficient to simply let the user do

    SuggestionType type = new SuggestionType("Import Problem");
    Suggestion s = mgr.createSuggestion(type, "Import java.awt.List");

because one of the key reasons we need a type is to be able to
store whether or not that type is enabled. Using the above, we'd
have to either take its class name and use that as the ID, or
force the user to declare an ID to go with it.

Having registries in the XML layer filesystem is actually done
in a number of places in NetBeans, for example the annotations
registry - although as you may have seen on nbdev, Jesse isn't
all that fond of it. I'm waiting to see if Yarda has good ideas
in this area.

> 2. Can  org.openide.text.Line be used to point to a directory? I can imagine
> suggestions like "use only lowercase letters for directory names" or
>     "split this package. It contains too many classes"

No, Line only points to file positions.  I think Line will be a lot
more common than pointing to directories, so it's convenient to
use Line here.   Clients can still implement what you're stating above;
it's just that the directory won't be shown in the File column.
Their SuggestionPerformer can easily navigate to any directory
they want and "show it"; unlike a Line which will probably be
shown in the editor, I suppose showing a directory means opening
an explorer on it?

I can also easily imagine tips wanting to use a URL as a resource,
instead of a Line or a file/directory.

> 3. Please insert values for PRIORITY_*-constants into JavaDoc

Why do you want to see the values there? (If I do that then the
actual values become part of the API and it's much harder to change
them (although as public-static-finals the values do get copied
directly into client classes on compilation, not the references.)

> 4.  DocumentSuggestionProvider operates only on one Document. My opinion is
> that SuggestionProviders like copyright-checker should be started
>      as a project is opened and should scan all files in the project in a
> background-thread with low priority. I don't want to open each file in the
> project
>      to find out that some of them use wrong copyright message. An audit
> module could also need to know dependencies between different files and so
> on.

The DocumentSuggestionProvider class is meant for the case where you're
scanning the current document; it helps track open documents, and user
"moves" between the documents. That's what nearly all the methods are
focused on.

For the scenario you're describing, simply subclass SuggestionProvider
instead. All the convenience methods built into
DocumentSuggestionProvider are useless in your case, because for
background scanning of all documents you don't care which documents
have been open, which document is currently showing, etc.  
SuggestionProvider gives you the basic hooks you need: notification
of when the Suggestions Window is opened, closed, etc, and you
can run your scanning in the background and access the SuggestionManager
to register your resulting suggestions.

> 5. Independent of (4): SuggestionProvider should have a method [double
> getProgress()] that returns it's progress in percents. We can use this
> information
>     to present a progress bar to the user.

I'd really like to avoid this: I think any "automatic" or "background"
suggestion analysis should be transparent to the user; only actions
which are started explicitly by the user should result in a progress
dialog.  In fact, I think I should state explicitly in the javadoc
that SuggestionProvider jobs should make sure they do not take
an excessive amount of computation; they need to spread their work
over multiple idle-invocations so that the user's machine does not
suddenly grind to a halt while they're editing for example.
And since the user does not know when the SuggestionProviders are
notified that they may check for work, user should not know that
one of them is for example 30% done with its task. In the end,
suggestions simply appear and disappear off the suggestions window
as necessary. 

Do you agree with that?

Thank you very much for the feedback, Tim!

-- Tor