X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=blobdiff_plain;f=doc%2Findex.org;h=873b0ddfc11983d3f6e0031fb8e38fcc6d16c922;hb=c508bf97e017675b49df989b7f5a64cbd31d9aa3;hp=1751f8d386e558c4ea6bf66bbf02a46773172d05;hpb=ad485fec491ab52453fedce0f7d5f5743f567009;p=javainspect.git

diff --git a/doc/index.org b/doc/index.org
index 1751f8d..873b0dd 100644
--- a/doc/index.org
+++ b/doc/index.org
@@ -18,35 +18,72 @@
 Goal: simplify/speed up understanding the computer program code by
 automatically visualizing its structure.
 
-JavaInspect is a Java library that you can embed into your Java
-project with a few lines of Maven configuration and then visualize any
-part of your Java program structure with few simple JavaInspect API
-calls at application runtime.
-
-JavaInspect uses Java reflection to discover class relations and
-structure and produces GraphViz dot file that describes your
-application. Then launches GraphViz to generate bitmap graph in PNG
-format on your Desktop directory.
-
-* Current status
-This is simple utility, quickly written. Tested on GNU Linux (can be
-relatively simply ported to other operating systems too). So far I
-used it for my own needs. There might be bugs and missing
-features. Feedback and code contributions are welcome.
+JavaInspect is a Java library that primarily uses Java reflection to
+discover and visualize any part of Java program provided that
+classes to be visualised are available in the classpath.
 
-* Example graphs
-Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]].
-
-A very simple example:
+JavaInspect currently has no GUI, configuration files, embedded
+scripting support, direct Maven or Ant integration. The only way to
+instuct Javainspect what to do is by using its Java API.
 
-[[file:example.png][file:example.resized.png]]
+To get JavaInspect into same classpath with your projecs I so far came
+up with 2 solutions:
 
+1. Add JavaInspect library in your project as a dependency.
+2. Create new Java project for the purpose visualizing your other
+   projects and include JavaInspect and your projecs binary artifacts
+   (Jar's) into new project classpath. Built binary Jar's (with no
+   source code) are sufficient because JavaInspect operates via
+   reflection.
 
-Graph legend:
+After discovering application structure and optionally filtering out
+unimportant parts, JavaInspect produces GraphViz dot file that
+describes data to be visualized. Then launches GraphViz to generate
+bitmap graph in PNG format. By default on your Desktop directory.
 
-file:legend.png
+Note: GraphViz is developed and tested so far only on GNU Linux.
 
-* Usage example 1
+* Example graphs
++ A very simple example:
+
+    [[file:example.png][file:example.resized.png]]
+
+    Graph legend:
+
+    file:legend.png
+
++ Example visualization of [[http://www2.svjatoslav.eu/gitbrowse/sixth/doc/][Sixth]] project: [[http://www2.svjatoslav.eu/projects/sixth/codegraphs/][architecture graphs]].
+
+* Usage
+Currently the only way to control JavaInspect is by using Java
+API. Simple Java based control/configuration code needs to be written
+for each project. I usually put such code into directories devoted for
+JUnit tests. Because it needs not to be compiled/embedded into final
+product or project artifact I'm just willing to visualize.
+
+Control code in general does the following:
+1. Create graph object.
+2. Java reflection/classloaders does not provide mechanism for
+   discovering all classes under given package. Therefore you need to
+   declare at least some classes to be added to the graph by:
+   + Manually adding individual classes to the graph.
+   + and/or: Let GraphViz recursively scan and parse specified
+     directories with Java source code files to discover class names.
+   + For every class added to the graph, GraphViz will recursively
+     inspect it and add all referecned classes to the graph as well.
+3. Graphs easilly get very big and complex so optionally we filter
+   important code using classname wildcards patterns based blacklist
+   and/or whitelist.
+4. Optionally we can tune some rendering parameters like:
+   + Possibility to remove orphaned classes (classes with no
+     references) from the graph.
+   + Specify target directory for generated visualization
+     files. (Default is user desktop directory)
+   + Keep intermediate GraphViz dot file for later inspection.
+5. Render graph.
+
+
+** example 1
 This example demonstrates generating of class graph from hand picked
 classes.
 
@@ -75,7 +112,7 @@ Result:
     - Generated DOT file: [[file:JavaInspect.dot][JavaInspect.dot]]
     - Generated PNG image: [[file:JavaInspect.png][JavaInspect.png]]
 
-* Usage example 2
+** example 2
 Recursively scan current directory for Java source code and attempt to
 detect class names from there to be added to the graph.