[platform-help-dev] Plugin documentation idea

[Dave Orme <DaveO@xxxxxxxxxxxxxxx>]

Title: Message

Perhaps I'm way off base here; in that case please point me in the correct direction and I will gladly repost this message.  However, I think I just thought of a way to present Eclipse plugin development in the documentation such that it will be much easier to:

 

1) Come up to speed

2) Figure out how to make a particular addition or modification after one already has a general idea of how everything fits together

 

Here it is (If it's already been done, somebody please point me in the correct direction :) :

 

Eclipse is basically this big hierarchy (well, a graph really but it's basically a hierarchy) starting with the engine, continuing with all of the plugin.xml files through the plugins and the extension points the plugins provide to other plugins, etc.

 

The thing I'm finding challenging in working with Eclipse is

 

1) Understanding the "big picture" of what the important plugins are, how they are connected (the hierarchy), and how they work together

2) figuring out where to hang my code

 

What I would like to see is a picture starting at the engine, showing what plugins plug in, their extension points, and what plugins extend those plugins, etc.  Then I would like to be able to expand detail in any particular area until I eventually drill down to the source code.

 

For example, the top level view would probably recursively show what plugins plug into what extension points all the way out to the leaf plugins.  It could also provide a brief description of the functionality provided by each plugin and the intended use for each extension point.  This way if I'm looking for a place to hang my new popup menu item (for example), I am likely to be able to guess pretty accurately simply by reading the plugin and extension point descriptions.

 

The next level down could be a detailed view of the plugin itself kind of like an annotated view of what the plugin.xml editor currently displays.  What I'd like to see different is *documentation* of what each extension point the plugin provides lets me do.  Probably a one or two line description would suffice although actually using some extension points may require me to call some API (for example to retrieve what the user just clicked) in which case it would be helpful if this level allowed "see also" links.

 

The next level down would let me browse the actual code for the plugin.  Maybe it would just take me to the Hierarchy view for the plugin's class.  Or perhaps it would take me to the JavaDoc page for the plugin's class.

 

The ideal would probably be for Eclipse to be able to generate this sort of documentation automatically from its own plugin registry plus (perhaps) documentation embedded in plugin.xml files and javadoc docs.

 

I hope these ideas help!

 

 

Best regards,

 

Dave Orme

Advanced Systems Concepts