OpenAPI Documentation/Question

Hello Shaun,

Actually the source code of CreateElementActionBase is provided as part of
the OpenAPI source code in the plugin development kit.

All available plugin development documentation is linked from either http://www.jetbrains.com/idea/plugins/plugin_developers.html
or http://www.jetbrains.net/confluence/display/IDEADEV/Home

I'm looking for an example of the DevKit's GeneratePluginActionBase
with a little more documentation. Even better would be to have better
documentation of the CreateElementActionBase. I am using the docs/jdk
for IntelliJ 7.0 (our company is standardized on this at this point)
and there doesn't see

m to be much in the way of documentation.

I'm wondering how I would begin to understand what is in the openapi
without having the examples given? I don't see what
CreateElementActionBase is really doing or what I should be passing to
it - at this point i'm only using the devkit as a guide. Wondering if
there are other guides I can use to help me move ahead.

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"

Thanks Dmitry,

I'm concerned about the documentation on a couple of levels.  But it may be that I just haven't looked hard.

For example,

I've reviewed the devkit project and am confused as to why PluginBuildCOnfiguration is extending BuildConfiguration.  I don't see any documentation that would support this.   Why the design decision to extend from BuildCOnfiguration?  It seems to me that PluginBuildCOnfiguration is how we are accessing a ConfigFile instance of plugin.xml.  If that is the case then why is it tucked into PluginBuildConfiguration?  I am confused as to why BuildConfiguration is even in the picture here.  Is this just simply a place that util methods were stashed?

Another area to discuss is the
CreateElementActionBase
CreateInPackageActionBase

I haven't found anywhere that states these are helper base files for performing what is a pretty typical and common task within a plugin.   How does one discover these abilities?   As of 7.0.5 these class have no javadoc, nor are there much in the way of centralized doc that says "You are typically performing this action and here is something that can be provided"

Further more it probably worth mention from Intellij what the difference is between the openAPI package and all the rest?  Is the OPENAPI package part of what IDEA has commited to not changing in the future?  There isn't a discernable documentation difference between openapi sub packages and the other packages.

Just a couple questions that I think have very beneficial answers for the community at large.

Hello Shaun,

I'm concerned about the documentation on a couple of levels. But it
may be that I just haven't looked hard.

For example,

I've reviewed the devkit project and am confused as to why
PluginBuildCOnfiguration is extending BuildConfiguration. I don't see
any documentation that would support this. Why the design decision
to extend from BuildCOnfiguration? It seems to me that
PluginBuildCOnfiguration is how we are accessing a ConfigFile instance
of plugin.xml. If that is the case then why
is it tucked into PluginBuildConfiguration? I am confused as to why
BuildConfiguration is even in the picture here. Is this just simply a
place that util methods were stashed?

Indeed, in this particular case it seems to be possible to extract the manifest/plugin.xml
management part of PluginBuildConfiguration to a separate class. However,
this is an implementation detail of the DevKit plugin, and we don't have
a goal of documenting all design decisions in all open-source plugins in
our OpenAPI documentation.

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"

Hello Shaun,

Another area to discuss is the
CreateElementActionBase
CreateInPackageActionBase
I haven't found anywhere that states these are helper base files for
performing what is a pretty typical and common task within a plugin.
How does one discover these abilities? As of 7.0.5 these class have
no javadoc, nor are there much in the way of centralized doc that says
"You are typically performing this action and here is something that
can be provided"

These abilities are usually discovered either by looking at the source code
of plugins which perform similar tasks, or by asking in this newsgroup. Indeed
there's little overview documentation describing common tasks and ways of
implementing them.

Further more it probably worth mention from Intellij what the
difference is between the openAPI package and all the rest? Is the
OPENAPI package part of what IDEA has commited to not changing in the
future? There isn't a discernable documentation difference between
openapi sub packages and the other packages.

The openapi package is mostly a historical legacy, and doesn't have any particular
meaning. OpenAPI is what's included in src_openapi.zip in DevKit.

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"

Hey Thanks for taking the time to answer these questions!

Another area to discuss is the
CreateElementActionBase
CreateInPackageActionBase
I haven't found anywhere that states these are helper base files for
performing what is a pretty typical and common task within a plugin.
How does one discover these abilities?   As of 7.0.5 these class have
no javadoc, nor are there much in the way of centralized doc that says
"You are typically performing this action and here is something that
can be provided"

These abilities are usually discovered either by looking at the source code
of plugins which perform similar tasks, or by asking in this newsgroup. Indeed
there's little overview documentation describing common tasks and ways of
implementing them.

Don't take this as me being rude but it would be huge for IDEA to start getting some better documentation in those packages.  I know your time is limited but it might help save a ton of time for everyone who is writing plugins for the IntelliJ IDE.

Further more it probably worth mention from Intellij what the
difference is between the openAPI package and all the rest?  Is the
OPENAPI package part of what IDEA has commited to not changing in the
future?  There isn't a discernable documentation difference between
openapi sub packages and the other packages.

The openapi package is mostly a historical legacy, and doesn't have any particular
meaning. OpenAPI is what's included in src_openapi.zip in DevKit.

--

So OpenAPI is basically just the source code that has been so far released.   The package itself is just an architectural legacy but the src package included with the DevKit will give us insight into operations.  It's possible that other classes will make it into the src package.  Is that what you mean when you say something will be included in the openApi?

Hello Shaun,

The openapi package is mostly a historical legacy, and doesn't have
any particular meaning. OpenAPI is what's included in src_openapi.zip
in DevKit.

--

So OpenAPI is basically just the source code that has been so far
released. The package itself is just an architectural legacy but the
src package included with the DevKit will give us insight into
operations. It's possible that other classes will make it into the
src package. Is that what you mean when you say something
will be included in the openApi?

Not only that. When we move a class to OpenAPI, we also try to review its
public interface and ensure that it's easy to understand and to use.

--
Dmitry Jemerov
Development Lead
JetBrains, Inc.
http://www.jetbrains.com/
"Develop with Pleasure!"