home.md

@@ -61,12 +61,13 @@ COJAC is offered (without warranty of any kind) in the hope it can be useful
 for educational purposes, as well as in the software industry. 
 
 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.
+[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 
 [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 a paper.
+wrapping feature is brand new and has not yet been discussed in any paper.
 
 Any comment/feedback is welcome!
 
@@ -161,7 +162,7 @@ You can  choose the way COJAC will inform you when a problem occurs:
 
 You can also configure what information COJAC will give you. Use the `-Sd` 
 option to have the detailed stack trace for each warning. You can also use 
-the `-Xt` to display the stats about the instrumentation, namely some 
+the `-Xt` to display the statistics about the instrumentation, namely some 
 information about how many bytecode instructions have been instrumented by COJAC. 
 
 COJAC provides a useful `-Xf` option which filters the warnings. For 
@@ -184,7 +185,7 @@ as a diagnostic-enabled java launching means.
 
 Here is a small example of what COJAC can do. Let's take a simple class like that: 
 
-```
+```java
 /*01*/ public class Demo {
 /*02*/   public static void main(String[] args) {
 /*03*/    int a = 2_000_000_000, b = 2_000_000_000;
@@ -223,7 +224,7 @@ get redirected to the edited file).
 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;
@@ -282,7 +283,7 @@ 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 
 provide those two methods: 
-```
+```java
   public static String COJAC_MAGIC_wrapperName();
   public static String COJAC_MAGIC_toString(double n); // internal representation
   
@@ -299,7 +300,7 @@ provide additional magic methods.
 
 Here is a small demo program. 
 
-```
+```java
 public class HelloMrCojac {  
   public static String COJAC_MAGIC_toString(double n) { return ""; }
   public static void main(String[] args) {
@@ -356,21 +357,20 @@ prompt> java -javaagent:cojac.jar="-Rb 2" HelloMrCojac
 
 The traditional float/double types compute approximate results (due to possible 
 rounding), but they can give no information at all about how far we get from 
-the "true" mathematical result. The idea behind *interval computation* technique of *reliable computing*  is to represent numbers with an interval that is guaranteed to hold the true 
-result, thus keeping track of the possible error margin. 
+the "true" mathematical result. The idea behind the *interval computation* technique of *reliable computing*  is to represent numbers with an interval that is guaranteed to hold the true result, thus keeping track of the possible error margin. 
 
 Our Interval wrapper is a toy realization of this technique. Internally, we emit
 a warning whenever the relative error of a number goes beyond a certain threshold 
 (that can be adjusted via an option).
 
 This wrapper is activated with the option `-Ri`. Two additional magic methods are defined for this model:
-```
+```java
 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 
-instance, we systematically round up/down instead of adjusing the 
+For now, we are yet far from a 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.
 
@@ -380,7 +380,7 @@ 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 
 alternative: roughly, the idea is to keep 3 versions of every arithmetic
-result, each corresponding to the application of a rounding mode choosen 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.
 
@@ -390,7 +390,8 @@ real breakthrough lies in the ease of our tool, which helps experimenting
 with the model.
 
 This wrapper is activated with the option `-Rs`. 
-That wrapper offers the same magic methods as our interval computation model.
+That wrapper offers the same magic methods as our interval computation model, 
+and is similar in its way of signaling high relative errors.
 
 ## 3.5 Number model "Automatic differentiation"
 
@@ -401,14 +402,14 @@ situation dramatically changes thanks to COJAC.
 
 This wrapper is activated with the option `-Ra`. 
 Here are the magic methods that are provided:
-```
+```java
 public static double COJAC_MAGIC_getDerivation(double a);
 public static double COJAC_MAGIC_asDerivationTarget(double a);
 ```
 
 Let's show them in action with a small example.
 
-```
+```java
 public class DerivationDemo {
   public static double COJAC_MAGIC_getDerivation(double a)      { return 0; }
   public static double COJAC_MAGIC_asDerivationTarget(double a) { return a; }
@@ -536,10 +537,23 @@ The sniffer part of COJAC is rather stable. Here are some limitations:
 The wrapper part of COJAC should be considered an experimental prototype. Here 
 are some limitations:
 
+* The frontier between "user code" and "java library" has some serious defects, eg 
+when arrays of numbers are involved.
+
+* We don't handle the "callbacks" from java library to the user code when floating 
+point numbers passed around.
+
+* We don't handle `invokedynamic`, so for the moment there are problems with
+java8 lambdas.
+
+* The use of Java reflection will break the logic of COJAC. 
 
+* The decision of converting both the primitive types float/double and their
+original wrapper Float/Double brings several problems, eg signature conflicts, or 
+comparison (compareTo/equals) misbehavior.
 
 * The implementation of the models is really naive. For instance, we do not compute
-the Math.* operations with the required precision with BigDecimals.
+every Math.* operations with the required precision with BigDecimals.
 
 --------------------------------------------------
 # 6. And now...