home.md

@@ -51,7 +51,8 @@
 Welcome to COJAC, a tool that leverages in new ways the arithmetic 
 capabilities of the Java programming language.
 
-Feel free to choose one of those acronym meaning:
+If you need a definition for the acronym "COJAC", feel free to choose one of 
+following:
 
 - `C`limbing `O`ver `J`ava `A`lgebraic `C`omputation
 - `C`reating `O`ther `J`uicy `A`rithmetic `C`apabilities
@@ -61,7 +62,7 @@ Feel free to choose one of those acronym meaning:
 COJAC is in fact a two-fold tool: 
 
 - a "numerical sniffer" that detects anomalies arising in arithmetic operations, 
-involving either integers (eg overflow) or floating point numbers (eg 
+on either integers (eg overflow) or floating point numbers (eg 
 cancellation or NaN outcome). This can be of great help to detect vicious bugs 
 involving annoying events that normally happen silently in the Java Virtual 
 Machine. See [§2](home#2-cojac-the-numerical-sniffer).
@@ -107,10 +108,10 @@ You might be interested in the
 [valgrind-based cousin](http://code.google.com/p/cojac-grind/cojac-grind), a 
 similar tool not limited to the Java world (it acts on any Linux binary).
 
-The concept of "numerical problem sniffer" is presented in our 
+The concept of _numerical problem sniffer_ is presented in our 
 [article](http://drdobbs.com/testing/232601564) published by Dr Dobb's 
 (remember how cool this journal was?). The revolutionary (but still experimental) 
-wrapping feature is brand new and has not yet been discussed in any paper.
+_wrapping feature_ is brand new and has not yet been discussed in any paper.
 
 Any comment/feedback is welcome!
 
@@ -137,7 +138,7 @@ The COJAC sniffer tracks the following kinds of event:
  * *Questionable comparisons*: two floating point numbers are being compared, but they are very close together. Example: `if (3.000001f >= 3.0f)...`
  * *Underflow*: the result of a division is so small that it gets rounded to zero. Example: `(2.5E-233 / 7.2E+233)`
  
-Note that all these example expressions, if they are written in Java like this, 
+Note that all these example expressions, when written verbatim in Java, 
 are evaluated at compile-time because they involve only literal values; so in 
 that (uninteresting) case, the problems won't be detected by COJAC (see 
 [known issues](home#51-issues-with-the-sniffer)).
@@ -147,13 +148,13 @@ that (uninteresting) case, the problems won't be detected by COJAC (see
 
 COJAC offers a fine-grained configuration of what must be instrumented in the application; the options let you select which category (or even which bytecode instructions) to watch:
 
- * *`-Ca`* Activates all possible detectors (this is the default behaviour)
- * *`-Cints`* Watches the "int" operations: `IADD,IDIV,IINC,ISUB,IMUL,INEG`
- * *`-Clongs`* Watches the "long" operations: `LADD,LDIV,LSUB,LMUL,LNEG`
- * *`-Cdoubles`* Watches the "double" operations: `DADD,DDIV,DSUB,DMUL,DREM`
- * *`-Cfloats`* Watches the "float" operations: `FADD,FDIV,FSUB,FMUL,FREM`
- * *`-Ccasts`*  Watches the typecasting operations: `L2I,I2S,I2C,I2B,D2F,D2I,D2L,F2I,F2L`
- * *`-Cmath`*  Watches the invocations of java.lang.Math methods, like `Math.sqrt` etc.
+ * *`-Ca`* to activates all possible detectors (this is the default behaviour)
+ * *`-Cints`* to watch the "int" operations: `IADD`,`IDIV`,`IINC`,`ISUB`,`IMUL`,`INEG`
+ * *`-Clongs`* to watch the "long" operations: `LADD`,`LDIV`,`LSUB`,`LMUL`,`LNEG`
+ * *`-Cdoubles`* to watch the "double" operations: `DADD`,`DDIV`,`DSUB`,`DMUL`,`DREM`
+ * *`-Cfloats`* to watch the "float" operations: `FADD`,`FDIV`,`FSUB`,`FMUL`,`FREM`
+ * *`-Ccasts`*  to watch the typecasting operations: `L2I`,`I2S`,`I2C`,`I2B`,`D2F`,`D2I`,`D2L`,`F2I`,`F2L`
+ * *`-Cmath`*  to watch the invocations of java.lang.Math methods, like `Math.sqrt` etc.
 
 By default, all detectors are activated.
 
@@ -268,11 +269,15 @@ COJAC gives the developer access to detection management through JMX.
 The management interface is the following:
 
 ```java
-Map<String, Integer> getCountersMBean() // gives every opcode instrumented with statistics;
-List<String>         getBlacklist() // offers the developer a means to know which methods are subject to annotation;
-Map<String, Long>    getEvent() // gives every detected event that occurred since the beginning of the application;
-void                 start() 
-void                 stop() // let you dynamically enable or disable the processing of the detected events.
+// gives every opcode instrumented with statistics
+Map<String, Integer> getCountersMBean() 
+// offers the developer a means to know which methods are subject to annotation
+List<String> getBlacklist() 
+// gives every detected event that occurred since the beginning of the application
+Map<String, Long> getEvent() ;
+// let you dynamically enable or disable the processing of the detected events.
+void start() 
+void stop() 
 ```
 
 The RMI service URL is parameterized by a couple of COJAC options. Here is 
@@ -307,7 +312,7 @@ activate, and there you go. Everywhere there are float/Float/double/Double data
 in user code (local variables, parameters, attributes...), they will be replaced
 by an object redefining the arithmetic behavior. As the code inside the Java library 
 cannot be transformed in such a way, we designed a mechanism that automatically 
-deals with the necessary conversions when the user code invokes a method from the
+deals with the necessary conversions when the user code invokes a method of the
 Java library (with the sad consequence that the "enrichment" is then lost).
 
 The "arithmetic behavior" that is embedded in our richer number types includes: 
@@ -322,8 +327,8 @@ The "arithmetic behavior" that is embedded in our richer number types includes:
 COJAC features a mechanism of *Magic Methods* that can be used to interact with 
 the new enriched numbers. A magic method has an identifier starting with 
 the prefix `COJAC_MAGIC_` and a specific signature, to be declared in user 
-code; at runtime, 
-COJAC will redirect the call to such methods to the implementation inside the wrapper,
+code; at runtime, COJAC will redirect the call to such methods 
+towards the implementation inside the wrapper,
 thus giving the user code access to the "richer number" power.
 
 The magic methods are model-specific (see below), but every number wrapper will at least 
@@ -338,7 +343,7 @@ public static String COJAC_MAGIC_toString(double n); // internal representation
 
 Our first "enriched number" type provides arbitrary precision numbers, where
 the number of significant digits is specified at runtime. The implementation 
-relies on the class java.math.BigDecimal. 
+relies on `java.math.BigDecimal`. 
 
 This wrapper is activated with the option `-Rb nDigits`, and it does not 
 provide additional magic methods.
@@ -414,7 +419,7 @@ public static double COJAC_MAGIC_relativeError(double n);
 public static double COJAC_MAGIC_width(double n); // interval width max-min
 ```
 
-For now, we are yet far from a the quality of a good "interval computation" library. For 
+For now, we are yet far from the quality of a good "interval computation" library. For 
 instance, we systematically round up/down instead of adjusting the 
 rounding mode. Nevertheless, the strength and simplicity of the automatic wrapping 
 should not be underestimated.
@@ -423,9 +428,9 @@ should not be underestimated.
 
 Interval computation is known to offer strong guarantees, but also to be overly 
 pessimistic in the estimation of the relative error (the interval is often far 
-wider than needed). "Discrete stochastic arithmetic" is an interesting 
+wider than needed). _Discrete stochastic arithmetic_ is an interesting 
 alternative: roughly, the idea is to keep 3 versions of every arithmetic
-result, each corresponding to the application of a rounding mode chosen randomly. 
+result, each corresponding to the application of a rounding mode chosen _randomly_. 
 An unstable computation has a high probability of producing 3 manifestly divergent 
 results, and the relative error can be estimated.
 
@@ -487,17 +492,17 @@ As you can check, the results are those expected!
 # 4 - Detailed usage
 
 
-Here is the full manpage-like description of COJAC, as produced by the help argument (`java -javaagent:cojac-1.1.jar="-h"`): 
+Here is the full manpage-like description of COJAC, as produced by the help argument (`java -javaagent:cojac.jar="-h"`): 
 
 ```
 usage: java -javaagent:cojac.jar="[OPTIONS]" YourApp [appArgs]
             (version 1.4 - 2015 Sep 22)
 
 Two nice tools to enrich Java arithmetic capabilities, on-the-fly:
-- Numeric Problem Sniffer: detects and signals arithmetic poisons like integer
+- Numerical Problem Sniffer: detects and signals arithmetic poisons like integer
   overflows, smearing and catastrophic cancellation, NaN or infinite results.
-- Wrapper for float/double: wraps every double/float in richer objects. Current
-  models include BigDecimal (you choose the precision), interval computation,
+- Enriching Wrapper for float/double: wraps every double/float in richer objects. 
+  Current models include BigDecimal (you choose the precision), interval computation,
   discrete stochastic arithmetic, and even automatic differentiation.
 ```
 ```
@@ -587,7 +592,8 @@ point numbers are being passed around.
 * We don't handle `invokedynamic` for the moment, so there are problems with
 java8 lambdas.
 
-* The use of Java reflection will break the logic of COJAC. 
+* We don't handle the possible use of Java reflection (in case of method 
+invocations via reflection, we don't apply the necessary transformations). 
 
 * The decision of converting both the primitive types float/double and their
 original wrapper Float/Double brings several problems, eg signature conflicts, or