Skip to content
Permalink
Browse files

more documentation cleanup

  • Loading branch information
matthiaskrgr authored and sbischoff-ai committed Sep 3, 2019
1 parent c678f60 commit e5f9f7fad9208ca7f7451c939efc971e03dac807
Showing with 19 additions and 17 deletions.
  1. +3 −3 CONTRIBUTING.md
  2. +3 −1 README.md
  3. +13 −13 docs/javadoc_guidelines.md
@@ -5,7 +5,7 @@ We use GitHub issues for both.
First, use the [github search](https://github.com/openvalidation/openvalidation/search?q=is%3Aissue&unscoped_q=is%3Aissue) to check if your issue has been reported already.
If you find that someone already reported your problem, feel free to share additional information to help us investigate the bug more quickly.

If you could not find a matching issue and want to open a new ticket, please try to follow the issue template and provide all the necessary information. However, an incomplete issue that reports a critical bug is still better than no issue at all.
If you could not find a matching issue and want to open a new ticket, please try to follow the issue template and provide all the necessary information. However, an incomplete ticket that reports a critical bug is still better than no ticket at all.

## Become a developer
Please refer to the [developer readme](/docs/developer_readme.md) for build and test instructions, as well as our coding guidelines.
@@ -24,9 +24,9 @@ We want to get openVALIDATION to be [checkstyle](https://checkstyle.org/) clean.
After having fixed all the warnings, submit a pull request.

#### Fixing bugs
Pick a ticket from the [bugtracker](https://github.com/openvalidation/openvalidation/issues) and let us know that you are working on a fix.
Pick a ticket from the [bugtracker](https://github.com/openvalidation/openvalidation/issues) and leave a comment letting us know that you are working on a fix.
If you have any questions, feel free to discuss it in the ticket.
Make sure the fix adheres to the [codeing guidelines](docs/developer_readme.md) guidelines.
Make sure the fix adheres to the [coding guidelines](docs/developer_readme.md).

#### Implementing new features
Before integrating a new feature, it's best to discuss it with the core developers first.
@@ -1,6 +1,8 @@
[![Build Status](https://dev.azure.com/validaria/openvalidation/_apis/build/status/openVALIDATION/openVALIDATION%20master?branchName=master)](https://dev.azure.com/validaria/openvalidation/_build/latest?definitionId=1&branchName=master)
![Azure DevOps tests (compact)](https://img.shields.io/azure-devops/tests/validaria/openvalidation/1?compact_message)
![Maven Central](https://img.shields.io/maven-central/v/io.openvalidation/openvalidation)
![Follow us on Twitter](https://img.shields.io/twitter/follow/Validaria_?style=social)


OpenVALIDATION enables you to generate validation rules from natural language-like expressions in English and German without any knowledge in programming.
The validation rules can be automatically translated by openVALIDATION into Java, JavaScript or C#, with more languages to come!
@@ -138,4 +140,4 @@ Please refer to our [contribution guidelines](CONTRIBUTING.md).

## Contact

You can mention our twitter account [@Validaria_](https://twitter.com/validaria_)
You can write an [E-Mail](mailto:todo) or mention our twitter account [@Validaria_](https://twitter.com/validaria_).
@@ -3,7 +3,7 @@
To ensure a homogeneous documentation and a high degree of readability and maintainability we want to
establish a few rules when it comes to documenting your (or somebody else's) code. Those rules (or guidelines)
are supposed to enable new contributors to quickly get a grasp of the code they are looking at and so keep the
process of understanding the project as frictionless as we can. To achieve that it is mandatory to keep Documentation
process of understanding the project as frictionless as we can. To achieve that it is mandatory to keep documentation
complete, consistent and readable.

### General
@@ -15,13 +15,13 @@ Every part of a JavaDoc comment needs to follow these rules:
- each element (header, body, the param-block, etc) is separated by a \<p>

```
Note that character limits are not hard limits. Depending on the complexity of the documented code the limit can be
Note that character limits are not hard limits. Depending on the complexity of the documented code, the limit can be
exceeded by quite a bit. Keep in mind, however to keep everything as short as possible.
```

### Header
The header exists to give a short explanation of the documented code's purpose.
- precise, single-line sentence describing the method or class
- a precise, single-line sentence describing the method or class
- no more than 100 characters
- should be plain text
- no in-depth context
@@ -42,7 +42,7 @@ purpose of the class or method. Some guidelines for the body:
- give context
- no more than 100 characters per line
- may use HTML tags
- reference other classes, methods etc. (@code and @link)
- reference other classes, methods etc. (`@code` and `@link`)
- can and should be split into multiple paragraphs (\<p>) for more complicated contexts

```
@@ -71,21 +71,21 @@ that the Body itself can also be divided into multiple paragraphs to keep readab
sophisticated contexts well structured.-->

### Params
The ```@param``` entries are used to explain the parameters given to a specific method. It is also necessary to
The `@param` entries are used to explain the parameters given to a specific method. It is also necessary to
clarify the behaviour of the method should a parameter be null. To do that we define this kind of behaviour as a suffix
behind the parameter explanation separated by a comma. The types of suffixes are:

| Suffix | Description |
| :-------------------- |:------------- |
| not null | parameter cannot be null. Will otherwise result in a ``NullPointerException``. |
| nullable -> [result] | parameter can be null. [result] represents a description of how a null value is handled. |
| null returns [value] | parameter can be null. A custom [value] can be defined as a return value, e.g. "null returns -1". |
| Suffix | Description |
| :------------------- | :------------------------------------------------------------------------------------------------ |
| not null | parameter cannot be null. Will otherwise result in a ``NullPointerException``. |
| nullable -> [result] | parameter can be null. [result] represents a description of how a null value is handled. |
| null returns [value] | parameter can be null. A custom [value] can be defined as a return value, e.g. "null returns -1". |

The parameter descriptions themselves should be no more a short description. If there is too much context to a parameter
it should be explained in the body of the JavaDoc comment. The general guidelines are:
- every parameter needs an ``@parameter``
- every parameter needs an `@parameter`
- every parameter needs one type of suffix specified in the table above
- the order of the ``@params`` is equivalent to the order they appear in the method header
- the order of the `@params` is equivalent to the order they appear in the method header
- description is no complete sentence

```java
@@ -100,7 +100,7 @@ public String foo(int number, Object obj){...}
```

### Returns
The ```@return``` describes the return value of a method's result. Use it as if ``@return`` initiates
The `@return` describes the return value of a method's result. Use it as if `@return` initiates
a sentence.
- keep it precise
- document it as if ist a sentence beginning with 'returns'

0 comments on commit e5f9f7f

Please sign in to comment.
You can’t perform that action at this time.