Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Intent/Use Cases"

(Screenshots)
Line 1: Line 1:
coming soon
+
<br>
 +
 
 +
THIS PAGE IS A WORK IN PROGRESS
 +
 
 +
 
 +
 
 +
This section is focused on describing Intent's main use cases, some features to support these use case might not be completely implemented yet but are at the top of the priority list.
 +
 
 +
== Retro-documentation of Existing Code  ==
 +
 
 +
The Intent project considers code or documentation have the same value and no one should necessarily be the first on the other, its focus is on making sure these are synchronized and helping the developper to keep them synchronized, one of the consequences of this statement is that it's a perfect tool to get started in documenting legacy code.
 +
 
 +
 
 +
 
 +
Let's take an sample scenario for this usage :
 +
 
 +
Alice want to document its existing Eclipse project, she starts a new empty documentation project.&nbsp;
 +
 
 +
Alice starts to organize the documentation through sections an introduction, &nbsp;a general design, a chapter dedicated to testing...
 +
 
 +
Alice has the ability i'''n the documentation '''
 +
 
 +
 
 +
<pre>@M
 +
  new PluginProject coreplugin {
 +
    id = "com.alicecompany.greatapp.core"
 +
  }
 +
@M
 +
 
 +
This plugin contains all the core services of greatapp [..] .
 +
 
 +
</pre>
 +
 
 +
 
 +
Alice describe, in a documentation section dedicated to the general architecture of her great app, &nbsp;the list of every PluginProject describing using natural langage.
 +
 
 +
In another chapter dedicated to the technical architecture she use the ability to complement her definition of the plugins describing the Java execution environment:
 +
 
 +
<br>
 +
<pre>@M
 +
coreplugin {
 +
  executionEnvironement = "J2SE-1.5"
 +
}
 +
M@</pre>
 +
&nbsp;
 +
 
 +
 
 +
 
 +
When Alice hit the save button, her document is being compared with her workspace content, if any de-synchronization is detected, markers are added at the corresponding position in the document.
 +
 
 +
The PluginProject model definition enforce the fact that every PluginProject has to describe the its API (exported packages and extension points) in the documentation.&nbsp;During the synchronization an error will be added on every PluginProject which is - in the workspace - providing an API which is not referenced in the documentation.
 +
 
 +
 
 +
 
 +
Alice might either fix those errors manually adding the corresponding model fragments or hit the quickfix intializing those:
 +
<pre>@M
 +
corePlugin {
 +
  extension-points += new ExtensionPoint {
 +
        id="thing-provider"
 +
  }
 +
}
 +
M@
 +
 
 +
bq. TODO ALICE : describe the extension point
 +
 
 +
@M
 +
corePlugin {
 +
  extension-points += new ExtensionPoint {
 +
        id="compilation-participant"
 +
  }
 +
@M
 +
 
 +
bq. TODO ALICE : describe the extension point
 +
 
 +
</pre>
 +
<br>
 +
 
 +
In a nutshell using the validation errors and quickfixes Alice is going to retro-document the whole project, furthermore once this is done, any rebuild of the documentation will check the development artifacts (Manifest.MF, plugin.xml and others) and will report inconsistencies.
 +
 
 +
 
 +
 
 +
This example is using EclipsePlugin as - in fact - an example, the ability to synchronize model fragments to "'''real world artifacts'''" &nbsp;is a completely extensible part of Intent powered by EMF models.
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
 
 +
== Document-driven design  ==
 +
 
 +
== Screenshots  ==
 +
 
 +
Searching through documentation using outline&nbsp;:
 +
 
 +
[[Image:Intent outline search.png|450x221px|450x221px[450x221]]
 +
 
 +
Getting synchronization issues between documentation and models concretely used by developers&nbsp;&nbsp;:
 +
 
 +
[[Image:Intent synchronizer example.png|400x201px|400x203px[400x203]]
 +
 
  
 
== Screenshots  ==
 
== Screenshots  ==

Revision as of 08:40, 3 February 2011


THIS PAGE IS A WORK IN PROGRESS


This section is focused on describing Intent's main use cases, some features to support these use case might not be completely implemented yet but are at the top of the priority list.

Retro-documentation of Existing Code

The Intent project considers code or documentation have the same value and no one should necessarily be the first on the other, its focus is on making sure these are synchronized and helping the developper to keep them synchronized, one of the consequences of this statement is that it's a perfect tool to get started in documenting legacy code.


Let's take an sample scenario for this usage :

Alice want to document its existing Eclipse project, she starts a new empty documentation project. 

Alice starts to organize the documentation through sections an introduction,  a general design, a chapter dedicated to testing...

Alice has the ability in the documentation


@M
   new PluginProject coreplugin {
     id = "com.alicecompany.greatapp.core"
  }
@M

This plugin contains all the core services of greatapp [..] .


Alice describe, in a documentation section dedicated to the general architecture of her great app,  the list of every PluginProject describing using natural langage.

In another chapter dedicated to the technical architecture she use the ability to complement her definition of the plugins describing the Java execution environment:


@M
coreplugin {
  executionEnvironement = "J2SE-1.5"
}
M@

 


When Alice hit the save button, her document is being compared with her workspace content, if any de-synchronization is detected, markers are added at the corresponding position in the document.

The PluginProject model definition enforce the fact that every PluginProject has to describe the its API (exported packages and extension points) in the documentation. During the synchronization an error will be added on every PluginProject which is - in the workspace - providing an API which is not referenced in the documentation.


Alice might either fix those errors manually adding the corresponding model fragments or hit the quickfix intializing those:

@M
corePlugin {
   extension-points += new ExtensionPoint { 
         id="thing-provider"
   }
}
M@

bq. TODO ALICE : describe the extension point

@M
corePlugin {
   extension-points += new ExtensionPoint {
         id="compilation-participant"
   }
@M

bq. TODO ALICE : describe the extension point


In a nutshell using the validation errors and quickfixes Alice is going to retro-document the whole project, furthermore once this is done, any rebuild of the documentation will check the development artifacts (Manifest.MF, plugin.xml and others) and will report inconsistencies.


This example is using EclipsePlugin as - in fact - an example, the ability to synchronize model fragments to "real world artifacts"  is a completely extensible part of Intent powered by EMF models.




Document-driven design

Screenshots

Searching through documentation using outline :

450x221px[450x221

Getting synchronization issues between documentation and models concretely used by developers  :

400x203px[400x203


Screenshots

Searching through documentation using outline :

450x221px[450x221

Getting synchronization issues between documentation and models concretely used by developers  :

400x203px[400x203

Back to the top