Fixes #75: rule doc not up-to-date with changes in PMD

Author: jensgerdes

sonar-pmd-plugin/src/main/resources/org/sonar/l10n/pmd/rules/pmd/OptimizableToArrayCall.html

@@ -1 +1,34 @@
-A call to Collection.toArray can use the Collection's size vs an empty Array of the desired type.
+<!-- (c) 2019 PMD -->
+<p>
+  Calls to a collection’s <code>toArray(E[])</code> method should specify a target array of zero size. This allows the
+  JVM to
+  optimize the memory allocation and copying as much as possible.
+</p>
+<p>
+  Previous versions of this rule (pre PMD 6.0.0) suggested the opposite, but current JVM implementations
+  perform always better, when they have full control over the target array. And allocation an array via
+  reflection is nowadays as fast as the direct allocation.
+</p>
+<p>
+  See also <a href="https://shipilev.net/blog/2016/arrays-wisdom-ancients/">Arrays of Wisdom of the Ancients</a>
+</p>
+<p>
+  Note: If you don’t need an array of the correct type, then the simple <code>toArray()</code> method without an array
+  is faster, but
+  returns only an array of type <code>Object[]</code>.
+</p>
+<h2>Noncompliant Code Example</h2>
+<pre>
+List&lt;Foo&gt; foos = getFoos();
+
+// inefficient, the array needs to be zeroed out by the jvm before it is handed over to the toArray method
+Foo[] fooArray = foos.toArray(new Foo[foos.size()]);
+</pre>
+<h2>Compliant Solution</h2>
+<pre>
+List&lt;Foo&gt; foos = getFoos();
+
+// much better; this one allows the jvm to allocate an array of the correct size and effectively skip
+// the zeroing, since each array element will be overridden anyways
+Foo[] fooArray = foos.toArray(new Foo[0]);
+</pre>