Skip to content

Commit

Permalink
English language improvements and corrections by Hanna Skiba.
Browse files Browse the repository at this point in the history
  • Loading branch information
@domseichter
domseichter committed Aug 28, 2013
1 parent fb5086a commit fdced03
Show file tree
Hide file tree
Showing 6 changed files with 88 additions and 91 deletions.
4 changes: 2 additions & 2 deletions src/site/xdoc/comparison.xml
View file
Expand Up @@ -10,9 +10,9 @@
<section name="Comparison of Quality-Check with similar classes">
<a name="overview" />
<p>
This page tries to compare
This page aims to compare
<em>Quality-Check</em>
with other classes like
with other classes such as
<code>org.springframework.util.Assert</code>
<a href="http://static.springsource.org/spring/docs/3.1.x/javadoc-api/org/springframework/util/Assert.html">[1]</a>
or
Expand Down
21 changes: 10 additions & 11 deletions src/site/xdoc/index.xml
View file
Expand Up @@ -8,24 +8,24 @@
</properties>
<body>

<section name="What is Quality-Project?">
<section name="What is Quality-Project?">
<p>
The goal of Quality-Project is to provide small Java libraries which assist you in writing higher quality code.
</p>
<p>
Currently it consists of two modules: <a href="qualitycheck.html">Quality-Check</a> and <a href="modules/quality-check/index.html">Quality-Test</a>.
<em>Quality-Check</em> provides basic runtime code quality checks. <em>Quality-Test</em>
includes several tools improve the quality of unit tests.
includes several tools to improve the quality of unit tests.
</p>
<p>
Here's some example code to show both modules.
Here is some example code to show both modules:
</p>
<subsection name="Quality-Check">
<p>
We believe that all method arguments have to be checked for
We believe that all method arguments must to be checked for
technical validity, to avoid technical errors such as <code>NullPointerExceptions</code>
or <code>IndexOutOfBoundsException</code>. <em>Quality-Check</em> provides several
checks to ensure your parameters are valid. For more information take a look in to the <a href="qualitycheck.html">introduction</a>.
checks to ensure your parameters are valid. For more information take a look at the <a href="qualitycheck.html">introduction</a>.
</p>
<source><![CDATA[
@ArgumentsChecked
Expand All @@ -38,10 +38,9 @@ void doSomething(final List<String> list) {
</subsection>
<subsection name="Quality-Test">
<p>
In our opinion unit tests should focus on testing algorithms and functional behaviour.
Way to often you have to care about test data instead. Therefore, <em>quality-test</em>
provides its <em>Blueprint</em> feature to construct objects where all attributes
are filled with values.
In our opinion, unit tests should focus on testing algorithms and functional behaviour.
Much too often, you have to deal with test data instead. Therefore, <em>quality-test</em>
provides its <em>Blueprint</em> feature to construct objects where all attributes are filled with values.
</p>
<source><![CDATA[
@Test
Expand All @@ -64,8 +63,8 @@ void testSomething() {
application. Questions can also be sent to our <a href="https://lists.sourceforge.net/lists/listinfo/qualitycheck-users">mailing list</a>.
</li>
<li>
Help with the documentation by pointing out areas that are lacking or unclear, and if you are so inclined,
submitting patches to correct it. You can quickly contribute rough thoughts by forking this project on
Help with the documentation by pointing out areas that are lacking or unclear, and if you like, you can
submit patches to correct it. You can quickly contribute your thoughts by forking this project on
<a target="_blank" href="https://github.com/before/quality-check">GitHub</a> or
downloading at <a target="_blank" href="https://sourceforge.net/projects/qualitycheck/">Sourceforge</a>
, or you can volunteer to help collate and organize information that is already there.
Expand Down
28 changes: 13 additions & 15 deletions src/site/xdoc/qualitycheck.xml
View file
Expand Up @@ -15,19 +15,19 @@
<code>org.springframework.util.Assert</code> <a href="http://static.springsource.org/spring/docs/3.1.x/javadoc-api/org/springframework/util/Assert.html">[1]</a>
or
<code>com.google.common.base.Preconditions</code> <a href="http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/base/Preconditions.html">[2]</a>
without the need to include big libraries or frameworks such as Spring or Guava. The package <em>Quality-Check</em> tries to
replace these libraries and provide all the basic code quality checks you need. (If you're familiar with those classes, just look at our
without the need to include big libraries or frameworks such as Spring or Guava. The package <em>Quality-Check</em> aims to
replace these libraries and provide all the basic code quality checks you need. (If you are familiar with those classes, just look at our
<a href="comparison.html">comparison</a> page.)
</p>
<p>
The checks provided here are typically used to validate method parameters and detect errors during runtime. To
detect
errors before runtime we use JSR-305 Annotations. With these annotations you are able to detect possible bugs
earlier. For more informations look at FindBugs™ JSR-305 support.
earlier. For more information look at FindBugs™ JSR-305 support.
</p>
<p>
We think that our module is particularly suitable for APIs, which contain their own domain objects and services that are validated
using <em>Quality-Check</em> not only functionally, but also technically. More over we provide an easy to use fail-fast description of an API
We consider our module as particularly suitable for APIs, which contain their own domain objects and services that are validated
using <em>Quality-Check</em> not only functionally, but also technically. Moreover, we provide an easy to use fail-fast description of an API
to immediately report at its interface any failure or condition that is likely to lead to failure.
</p>
<p>
Expand All @@ -39,8 +39,8 @@
</section>
<section name="Why is it called check and not assertion?">
<p>We think that checks of method arguments are not only assertion tests it's more over a condition to work properly.
Beyond this, it supports you to write faster contracts for your methods and classes. If nothing of this package make
sense look at the concept
Beyond this, it supports you in writing faster contracts for your methods and classes. If nothing of this package makes
sense please take a look at the concept
<a href="http://en.wikipedia.org/wiki/Design_by_contract"><em>design by contract</em></a>.
</p>
</section>
Expand Down Expand Up @@ -72,7 +72,7 @@ setObject(final Object object) {
</section>
<section name="Why use Quality-Checks for your method parameters?">
<p>
<em>Quality-Check</em> brings several advantages to your project. If used extensivel throughout your codebase, you will benefit from the
<em>Quality-Check</em> brings several advantages to your project. If used extensively throughout your codebase, you will benefit from the
following points. We will outline each one in a short paragraph below.
</p>
<ul>
Expand Down Expand Up @@ -109,8 +109,8 @@ setObject(final Object object) {
Often, in Java development, you have to deal with
<code>NullPointerExceptions</code>
or other faults which can be tracked back to invalid values
passed to methods and handed further down till they
crash in your code. Sometimes it is hard to trace down where the
passed to methods and handed further down until they
crash in your code. Sometimes, it is hard to trace down where the
invalid value came from.
To identify invalid values
as soon as possible and detect errors where they occur, we suggest to guard every public
Expand All @@ -137,9 +137,7 @@ void doSomething(final List<String> list) {
}]]></source>
<p>
In this example, you would have to write two additional tests (one with a null list and one with an empty list),
just
to test these to branches -
or, if you do not, your branch coverage will go down.
only to test these two branches. Alternatively, if you do not, your branch coverage will go down.
</p>
<p>
<em>Quality-Checks</em> will save you from doing so! As calls to
Expand Down Expand Up @@ -177,9 +175,9 @@ void doSomething(final List<String> list) {
}
}]]></source>
<p>
As quality check throws the exceptions and your code does not there is no need for you to document these
As quality check throws the exceptions and your code does not, there is no need for you to document these
exceptions. You can focus
on the real important documentation of exceptions which might be thrown by business logic.
on the really important documentation of exceptions which might be thrown by business logic.
To show the caller of the
method that
quality-checks are in place and certain exceptions might be thrown, we add an
Expand Down
16 changes: 8 additions & 8 deletions src/site/xdoc/qualitytest.xml
View file
Expand Up @@ -28,9 +28,9 @@
Additionally, there are utils to give additional code coverage for private constructors.
</p>
<p>
Quality-Test often can be used together with Google Reflections (http://code.google.com/p/reflections/)
to perform checks such as, assure that every class in package *.dto.* is final
or make sure that no class in the package *.controller.* contains any non-final static variables.
Quality-Test can often be used together with Google Reflections (http://code.google.com/p/reflections/)
to perform checks such as assuring that every class in package *.dto.* is final
or making sure that no class in the package *.controller.* contains any non-final static variables.
</p>
<source><![CDATA[
@Test
Expand All @@ -42,8 +42,8 @@ public void testStaticAttributes() {
</section>
<section name="Coverage">
<p>
The coverage feature currently allows to give coverage to private constructors.
It is good practice to add private constructors to utility classes that are not thought to be instantiated. This is usually the case for final classes that only have static methods or provide constants (in the latter case I would suggest to use an interface).
The coverage feature currently allows giving coverage to private constructors.
It is good practice to add private constructors to utility classes that are not thought to be instantiated. This is usually the case for final classes that only have static methods or provide constants (in the latter case, I would suggest to use an interface).
</p>
<p>
Following this practice usually gives a bad surprise when looking at your Cobertura code-coverage report (or similar). The tool reports that the constructor is not covered - of course, because you cannot call it! This lowers your overall percentage for line-coverage and is a drawback when you otherwise try to achieve 100% line-coverage and also enforce this using mvn verify or similar methods.
Expand All @@ -55,7 +55,7 @@ public void testStaticAttributes() {
</section>
<section name="Blueprint">
<p>
The biggest part is Blueprint. A framework to automatically fill objects with test data. It is best shown in an example
The biggest part is Blueprint. A framework to automatically fill objects with test data. It is best shown in an example:
</p>
<source><![CDATA[
final NameDTO name = Blueprint.random()
Expand All @@ -65,9 +65,9 @@ public void testStaticAttributes() {
.with(String.class, "Default").with("zipCode", 12345L).construct(Address.class);
]]></source>
<p>
As you can see, <em>Blueprint</em> contains two default configurations, which either fill all attributes using default or random values.
As you can see, <em>Blueprint</em> contains two default configurations, which either fill all attributes using default or all attributes using random values.
Basically, Blueprint will walk the object tree and fill all attributes with default values specified by the current configuration.
Therefore, you won't get any <code>NullPointerExceptions</code> in your test-cases, as all attributes are filled with values.
Therefore, you will not get any <code>NullPointerExceptions</code> in your test-cases, as all attributes are filled with values.
You have to specify only those values on which your functional test-case actually depends. Everything else is handled by <em>blueprint</em>.
</p>
</section>
Expand Down
104 changes: 52 additions & 52 deletions src/site/xdoc/quickstart.xml
View file
@@ -1,53 +1,53 @@
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
<properties>
<title>Quick Start with Apache Maven</title>
<author>André Rouél</author>
</properties>
<body>
<section name="Quick Start with Maven">
<p>
If you use Apache Maven for your project, it's very easy to start using <em>Quality-Check</em> or <em>Quality-Test</em>,
because all artifacts are in
<a target="_blank" href="http://search.maven.org/#search%7Cga%7C1%7Cquality-check">The Central Repository</a>.
This repository is used by default to search for libraries.
</p>
<p>
Just add the following dependencies to your Project Object Model (POM). You know, the file called
<em>pom.xml</em>. Of course, you may want to only use one of the projects, e.g. only quality-check
and not quality-test. In this case only the dependency to quality-check is needed.
</p>
<source><![CDATA[<project>
...
<dependencies>
...
<dependency>
<groupId>net.sf.qualitycheck</groupId>
<artifactId>quality-check</artifactId>
<version>1.3</version>
</dependency>
...
<dependency>
<groupId>net.sf.qualitycheck</groupId>
<artifactId>quality-test</artifactId>
<version>1.3</version>
<scope>test</scope>
</dependency>
...
</dependencies>
...
</project>
]]></source>
<p>
Maven will now transitively resolve all dependencies to
<a href="modules/quality-check/index.html">Quality-Check</a>
and
<a target="_blank" href="http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jsr305%22">JSR-305 Annotations</a>
or <a href="modules/quality-test/index.html">Quality-Test</a>.
Now you're good to go with the next step:
<a href="usage.html">Usage in your API</a>.
</p>
</section>
</body>
<?xml version="1.0" encoding="UTF-8"?>
<document xmlns="http://maven.apache.org/XDOC/2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">
<properties>
<title>Quick Start with Apache Maven</title>
<author>André Rouél</author>
</properties>
<body>
<section name="Quick Start with Maven">
<p>
If you use Apache Maven for your project, it is very easy to start using <em>Quality-Check</em> or <em>Quality-Test</em>,
because all artifacts are in
<a target="_blank" href="http://search.maven.org/#search%7Cga%7C1%7Cquality-check">The Central Repository</a>.
This repository is used by default to search for libraries.
</p>
<p>
Just add the following dependencies to your Project Object Model (POM). You know, the file called
<em>pom.xml</em>. Of course, you may want to only use one of the projects, e. g. only quality-check
and not quality-test. In this case only the dependency to quality-check is needed.
</p>
<source><![CDATA[<project>
...
<dependencies>
...
<dependency>
<groupId>net.sf.qualitycheck</groupId>
<artifactId>quality-check</artifactId>
<version>1.3</version>
</dependency>
...
<dependency>
<groupId>net.sf.qualitycheck</groupId>
<artifactId>quality-test</artifactId>
<version>1.3</version>
<scope>test</scope>
</dependency>
...
</dependencies>
...
</project>
]]></source>
<p>
Maven will now transitively resolve all dependencies to
<a href="modules/quality-check/index.html">Quality-Check</a>
and
<a target="_blank" href="http://search.maven.org/#search%7Cga%7C1%7Ca%3A%22jsr305%22">JSR-305 Annotations</a>
or <a href="modules/quality-test/index.html">Quality-Test</a>.
Now you're good to go with the next step:
<a href="usage.html">Usage in your API</a>.
</p>
</section>
</body>
</document>
6 changes: 3 additions & 3 deletions src/site/xdoc/usage.xml
View file
Expand Up @@ -12,7 +12,7 @@
<p>
This means that if the
<em>Quality-Check</em>
library is used also the JSR-305 library must exist in your classpath.
library is used, the JSR-305 library must exist in your classpath.
</p>
<h3>A simple use case</h3>
<p>
Expand All @@ -21,9 +21,9 @@
quickly.
</p>
<p>
Then you should have access to the classes of the library. For example, you might want to build an
Now you require access to the classes of the library. For example, you might want to build an
<em>immutable</em>
object as the following example.
object as shown in the following example:
</p>
<h4>
<span class="green">
Expand Down

0 comments on commit fdced03

Please sign in to comment.