Poll: What is the most important thing for reducing plugin development pain?

1) Javadoc, javadoc, javadoc.

2) "How do I hook into the system, and what functionality is available" where ]]> is anything like inspections, intentions, version control, lvcs, editor, refactoring, etc., etc.

3) Usage and examples of using the testing framework.

Glad to see this is being addressed. It's probably the most important single improvement that could be made.

--Dave Griffith

Hello Dmitry,

my wishlist:

- more samples
- ofcourse better JavaDoc, at least package-level JavaDoc would help a lot when entering the joys of OpenAPI ;)
- more HowTos
- maybe OpenAPI-users can submit patches for JavaDoc in JIRA (or a WiKi-like system) to be included by JB after review

Thanks,
Yann

Dmitry Jemerov (JetBrains) wrote:

Hello everyone,

The poor state of documentation for the IDEA OpenAPI and other problems
with it have been a common source of complaints from IDEA users. The
complaints did not fall on deaf ears. :) I have recently joined the
IDEA team as a developer, and one of my primary responsibilities is
improving the OpenAPI, its documentation and the support we provide for
plugin developers.

Great, I'm excited about this.

Eventually we plan to have our entire OpenAPI documented, but given the
sheer volume of the work involved, this isn't likely to happen earlier
than the next major release of IDEA. Because of this, I would like to
ask the plugin developers: What would be the most helpful thing we can
provide in the near term? Do you simply need more javadoc documentation
for the OpenAPI classes? More overview- or tutorial-style articles on
plugin development? More samples for specific areas of the OpenAPI?

Unfortunately I think the answers are yes, yes, yes. I don't think any
of these is more important than the others. I personally only want
Javadoc, but I'm familiar with the OpenAPI and my biggest problems with
it lately are when I don't understand exactly what a method does, or
what a class or interface is for. However, I think you should focus on
new plugin developers first, by providing samples and overviews.

> What specific areas do we need to cover first in our documentation?

I don't use Eclipse and I don't feel that there's a lack of plug-ins for
IDEA for the things I use. So, I'm not such a good source of information
about this. However, I think you should look at popular plugins for
Eclipse and NetBeans, such as Hibernate and Tapestry support, and see
which features of the OpenAPI must be used to recreate them as IDEA
plugins. Then, you could document those first.

I'd say the most obvious immediate need is for some comments and package
overviews
in the Javadocs. What does this method return, do I need to know about it
or can
it be ignored.

An faq/wiki or even examples on doing some of the more common operations
(and the gotchas).
Working with editors, psi elements, intentions, virtual file system, vcs
integration, language
support etc.. the forums aren't a bad source of information, but between
that and the old plugin dev site they'res a lot of dated information floating
around.

Stability of the OpenAPIs is another bugbear, seems that every new release
needs some
re-write or other. Not every plugin developer can afford to keep up this
maintenance.

Found myself wondering about CVS/SVN for plugin sources. Wether a more obvious
source control
system might not encourage more contributions (and not just from the developer).
Sure I could
start a java.net or sourceforge project, but that seems like overkill.

The Eclipse boys seem to do this quite well, why not turn the tables on them
an nick a few of their ideas for a change ;)

- Richard

Dmitry,

personally I don't heavily depend on an extremely polished documentation. For most things
I'm happy with properly named identifiers and some basic how-to-use examples to get
started. This is mainly an effect of the various completion and navigation methods that
make it easy to browse code and to find the things you need.

So to answer your question, there should be

1) Some basic documentation about the different concepts in IDEA. There's already a basic
start with the "Plugin Development Readme" and "Action System" documents, but there's room
for a lot more. This is especially important for developers who didn't follow the evolving
of the OpenAPI from the beginning, when it was fairly simple.

2) Some annotated code samples that illustrate those concepts to get an idea where to
start from. The current release with plugins for many different aspects is a good start,
but are too complex and non-documented to be really useful. I've been looking at the
WebLogic integration once and thought by myself, "ok, I'll never bother to understand this".

3) JavaDoc for classes and methods whose usage are not obvious from their naming. A recent
example: I had no clue what PsiReference.isSoft() is supposed to be responsible for. The
name isSoft() is not informative enough to realize the functionality immediately.
Especially because the difference will only become obvious in certain situations.

This kind of JavaDoc coverage is the absolute bare minimum and should probably be combined
with 1)/2) in form of package.html documentation and short descriptions of a class' or
method's responsibilities.

One other thing however that I think is a great problem is the fact that the so-called
"OpenAPI" has a quite limited usefulness - at least when doing things that are slightly
more complex than opening a toolwindow or making simple editor modifications. Even without
any further documentation or stability guarantees, I'd kill to know some parameter names
from the idea.jar-API. There's so much useful stuff in there, but

- People just don't know about it (idea.jar isn't added by default to an IDEA-JDK, despite
the fact that you need it for language-development).
- People don't dare to use it (but hey, the "OpenAPI" itself won't win a stability price
either, so the risk for something to change and break is present anyway).
- People don't know how to (properly) use it, because parameter names are gone and not
everybody has the patience and/or talent to figure this out in long night-shifts.


Sascha

2) Some annotated code samples that illustrate those concepts to get an idea where to
start from.

+1

I do think the javadoc for PSI is the most important.

It's pretty tricky how to use this API. I surely miss alot of Helper classes that can do all the dumb/bulk work of figuring out how to get eg. from a PsiType to it's PsiClass.
Also there are some pitfalls dealing with the simple types.

I guess a good tutorial would be to walk through a plugin that could edit the javadocs for a given java file. This demonstrates how it's possible to get the current editing javafile (if it's a javafile). Traversing some of the cumbersome PsiXXX code to find all the methods of the class. And determining the method parameters, throws exceptions etc. And if the method already have a javadoc.

The plugin could have an intention to edit/add javadoc for the method.

And there could be an inspection to inspect if the class have methods without javadocs, or out-of-sync javadocs.

An advanced topic could be all the new JDK1.5 related enhancements to the API - annotations, enum, generics.

Another issue with the open API I miss is UI components. It's hard to have UI consistency with IDEA if you can't reuse it's components or extend/modify them for your needs.

There are some dialogs you can use but there aren't always in the openapi and thus hard to figure it's parameters.

Hello Claus,

CI> Another issue with the open API I miss is UI components. It's hard
CI> to have UI consistency with IDEA if you can't reuse it's components
CI> or extend/modify them for your needs.
CI>
CI> There are some dialogs you can use but there aren't always in the
CI> openapi and thus hard to figure it's parameters.

Feel free to file requests listing the dialogs you would like to access from
your plugins, and we'll see what we can do about exposing them through OpenAPI.

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

One thing I haven't seen mentioned is a decent pallette to use for GUI development for plugins.

It'd be nice to have an IDEA pallette, which includes TableView, TreeView, the fancy splitpane, ColoredComponent, and the other goodies.

An step-by-step tutorial for the Language-API. It's a pain starting with
the JavaScriptPlugin.
It should start from the very basic and then explain the various
concepts (highlighting, annotations, formatting, references) and what
has to be implemented for them. I suppose by writing such an tutorial,
one would get an good overview of the pitfalls of the api.
An template for start working wrong would help creating the initial
classes. There is so much which could be automated here.

Up

I think the language API is going to become increasingly important so +1 to that.

1)
I need to mimic the CTRL + E dialog. (Recent Files). I haven't found it in the OpenAPI so I needed to code one my self.

2)
com.intellij.ui.OrderPanel
Is it possible to get access to the UI componenet for the buttons (Add, Remove)

3)
Genereally alot of the nice UI components from the Settings would be great if they could be reused. It is cumbersome to create a nice settings UI for your plugin if you have to use plain old Swing.

I'm bringing this up again since Demetra includes new OpenAPI stuff which is not documented at all. I hope this will not be the case again for subsequent EAPreleases ;)

Hello Yann,

YC> I'm bringing this up again since Demetra includes new OpenAPI stuff
YC> which is not documented at all. I hope this will not be the case
YC> again for subsequent EAPreleases ;)

I expect to be able to dedicate considerably more time to OpenAPI documentation
closer to the release of Demetra. Right now I'm mostly working on the UI
Designer, not on OpenAPI.

Note, however, the nearly fully documented global inspections API. :)

--
Dmitry Jemerov
Software Developer
JetBrains, Inc.
http://www.jetbrains.com
"Develop with pleasure!"

As a long-time Eclipse user, I've actually found Idea plugins much easier to write. The debug messages in Idea were especially useful getting it to work!

My suggestions would be:-
1. More intermediate examples (jumping into the Javascript or ImageViewer examples is quite a challenge and they do could contain more comments). Some 'boilerplate' examples would be useful as a starting point.
2. More links to code snippets and cross-referencing so it is easy to find out specifics.

MArkee

The most important thing, is not JavaDoc etc, the most important thing - is plugin writers friendly support from JetBrains :)

We will hapy, when our plugin will be carried by great plugin repository, JIRA tracker, Confluence pages and Updatable Almanac of OpenAPI.

And another one pain - is compatibility. We can't track successfuly then our plugin is come to broken state. It maybe tested authomaticaly by testing frameworks on repository server side. Then new build is available, something like CC will get every one plugin with valid since-build and untile-build and spin up test. In fail case, the mail or JIRA issue posted to author.

Thanks!

Hello Alexey,

We do have similar ideas in reagrds to new build server stuff but they most
probably won't be implemented in first version.

-

Maxim Shafirov
JetBrains, Inc
http://www.jetbrains.com
"Develop with pleasure!"

The most important thing, is not JavaDoc etc, the most important thing
- is plugin writers friendly support from JetBrains :)

We will hapy, when our plugin will be carried by great plugin
repository, JIRA tracker, Confluence pages and Updatable Almanac of
OpenAPI.

And another one pain - is compatibility. We can't track successfuly
then our plugin is come to broken state. It maybe tested authomaticaly
by testing frameworks on repository server side. Then new build is
available, something like CC will get every one plugin with valid
since-build and untile-build and spin up test. In fail case, the mail
or JIRA issue posted to author.

Thanks!

It would be nice if at least proper @since 6.0 tags would be added to new methods/classes, e.g. Language is missing some