OpenAPI documentation

I have a dream that one day this documentation will rise up and live out the true meaning of it's usefulness: "We hold these words to be self-evident: that all plugins created are equal". I have a dream that one day on the red hills of St. Petersburg the JetBrains employees and third party programmers will be able to sit down together at a table of brotherhood, and share their knowledge of the OpenAPI. I have a dream that even the state of PSI, a state of obfuscation and darkness will be transformed into an oasis of freedom and well documented API. I have a dream that my four projects will live in an IDE where they will not be programmed by guessing method names, but by the contents of the documentation. I have a dream today.

Am I dreaming too far away?

8 comments
Comment actions Permalink

I'm really impressed! :)
The sad truth is developing mature documentation is equally hard tasks to
those we have pending in our JIRA. Thus, if we take it really serious many
of them will probably fell out.
-


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



0
Comment actions Permalink

So if an comprehensive documentation is not possible, it would be a
great help to have at least one or two examples from JetBrains for most
parts of the open api.
With the 3xxx builds the open api has become really huge and I don't
even have an idea on how to use most of it.
(take the lang+lexer packages. I suppose they are used to write plugins
for foreign languages. But no guess how to implement the lexer interface.)

Sven.


Maxim Shafirov schrieb:

I'm really impressed! :)
The sad truth is developing mature documentation is equally hard tasks
to those we have pending in our JIRA. Thus, if we take it really serious
many of them will probably fell out.

0
Comment actions Permalink

The sad truth is developing mature documentation is
equally hard tasks to
those we have pending in our JIRA. Thus, if we take
it really serious many
of them will probably fell out.


And the sadder truth is, this documentation should be taken seriously. On the previous company I worked at, I failed lobbying IDEA as a standard IDE exactly because it didn't have a decent and fully documented open API for extensions.

With the growing popularity of Eclipse (something which can't be stopped, unfortunately), I think it's important to position IDEA as an open platform. Of course, I don't expect the same number of plugins to be written, even if the OpenAPI is fully documented, but it's reasonable to expect a lot more of third party integration if it was easier to write plugins for IDEA, and good documentation (javadocs at a minimum) has a key role in this process.

Business-wise, it would be great for IDEA to have a fully documented OpenAPI. Most programmers nowadays expect some level of integration from frameworks. Just take a look around, and you will noticed that basically every popular framework or product has some level of tooling support for Eclipse, specially the open source frameworks. Wouldn't it be great for us if we could get the same level of tooling in IDEA? Wouldn't it be great for IDEA if it could have the same level of third-party support?

Sure, there are other features to be done and bugs to be fixed, but I would choose polishing and documenting the OpenAPI over most of the features currently open in the tracker.

0
Comment actions Permalink

On the previous company I worked at, I failed lobbying IDEA
as a standard IDE exactly because it didn't have a decent and fully
documented open API for extensions.

Exactly the same happed to me in my previous 2 projects(teams). We ended
up writing Eclipse plug-ins - the worst part was that I need to use Eclipse
to develop the plugins :).

and good documentation (javadocs at
a minimum) has a key role in this process.

Maybe Jetbrains could start with a few simple steps for the javadocs:
- adding a package.html (jbuilder did it automatically 4 years ago ;) )
so that one gets a little overview in the javadocs about what the diff. packages
contain.
- deleting from the sources disturbing information - the programmer thinks
that it's maybe some text,some docs or at least a phrase, and than...,
A: "author: xxx"(this belongs only in the CVS)
B: "Created by IntelliJ IDEA. User: xxx Date: xxxxxx PM To change this template
use File | Settings | File Templates."

Sure, there are other features to be done and bugs to be fixed, but I
would choose polishing and documenting the OpenAPI over most of the
features currently open in the tracker.

Maybe there's a solution to have them both:
JetBrains could publish the OpenAPI with a platform similar to "http://www.jdocs.com"
(but on their own server) so that advanced users can annotate it. With the
next EAP release, Jetbrains would integrate the annotations into the source
code and republish the API with the same framework to repeat the process.
This way, even users could contribute to improve the Docs, and at least to
"mark with tags" where they don't understand, so that JetBrains could concentrate
on those classes, not on the entire 45MB API :).

Thanks in advance,

Ahmed.

0
Comment actions Permalink

Ahmed Mohombe wrote:

JetBrains could publish the OpenAPI with a platform similar to "http://www.jdocs.com"
(but on their own server) so that advanced users can annotate it. With the
next EAP release, Jetbrains would integrate the annotations into the source
code and republish the API with the same framework to repeat the process.
This way, even users could contribute to improve the Docs, and at least to
"mark with tags" where they don't understand, so that JetBrains could concentrate
on those classes, not on the entire 45MB API :).


I like this suggestion and I would be willing to contribute to it. A lot
of information about the openapi is actually available, but it is
extremely spread out over javadoc, wiki, the forums and the heads plugin
authors. There just needs to be a place to collect it all and I don't
think the current wiki is enough for that.
Also in addition to javadoc I think there should be some other
introductory documentation or article(s). Unfortenately I'm not much of
a writer...

Bas

0
Comment actions Permalink

On Thu, 24 Feb 2005 18:16:48 +0300, Marcus Brito wrote:

And the sadder truth is, this documentation should be taken seriously.
On the previous company I worked at, I failed lobbying IDEA as a standard
IDE exactly because it didn't have a decent and fully documented open API
for extensions.


I was thinking it would be great for us plugin developers to start
maintaining our OWN plugin documentation pages from what we ourselves
already know. We would of course need input from JB over some of the
finer points thou.

JetBrains now have this nice shiny Confluence installation which would be
just ripe for us to start entering stuff into ( I know theres also the
existing wiki as well ).

However, I just headed over to it ( http://jetbrains.net/confluence ) and
saw the IDEADEV space which doesn't seem to have much in it yet, only -
the moment I logged into my account, this space dissapeared from view :(

Doh

0
Comment actions Permalink

Ahmed Mohombe

Maybe there's a solution to have them both:
JetBrains could publish the OpenAPI with a platform similar to
"http://www.jdocs.com" (but on their own server) so that advanced
users can annotate it.



This old request would come handy, if part of the javadoc was remote:
"Ctrl-Q : include doc sources other than the JDK ? "
http://www.intellij.net/tracker/idea/viewSCR?publicId=10576

Alain

0
Comment actions Permalink

I agree with the few comments that have been said: even just a few
javadocs here and there would already go a long way into helping
us understand how things work.

You could decide to answer questions posted in the openapi newsgroup
by adding new javadocs to the relevant spots in the OpenAPI, capturing
the knowledge directly in the source. :)

Vince.


0

Please sign in to leave a comment.