Merge pull request #487 from tamaro-skaljic/patch-1

Improve the documentation

asciidoc/src/main/docs/asciidoc/basic/concepts.adoc

@@ -38,7 +38,7 @@ can affect your application and if so then think about adding more limits.
 Limitations that are used by bucket can be denoted in terms of bandwidths. Bandwidth is denoted by the following terms:
 
 Capacity::
-`Capacity` is the term that is directly inherited from the classic interpretation of the token-bucket algorithm, this specifies how many tokens your bucket has. Refill must be configured during building stage
+`Capacity` is the term that is directly inherited from the classic interpretation of the token-bucket algorithm, this specifies how many tokens your bucket has.
 Capacity must be configured during building stage
 [source, java]
 ----
@@ -134,7 +134,7 @@ BucketState is the place where bucket stores own mutable state like:
 * Amount of currently available tokens.
 * Timestamp when the last refill was happen.
 
-`BucketState` is represented by interface https://github.com/bucket4j/bucket4j/blob/{minor-number}/bucket4j-core/src/main/java/io/github/bucket4j/Bucket.java[io.github.bucket4j.BucketState]. Usually you never interact with this interface, excepting the cases when you want to get access to low-level diagnostic API that is described in
+`BucketState` is represented by interface https://github.com/bucket4j/bucket4j/blob/{minor-number}/bucket4j-core/src/main/java/io/github/bucket4j/Bucket.java[io.github.bucket4j.BucketState]. Usually you never interact with this interface, excepting the cases when you want to get access to low-level diagnostic API that is described in <<verbose-api>>.
 
 
 [[local-bucket-builder, BucketBuilder]]
@@ -153,4 +153,4 @@ Bucket bucket = Bucket.builder()
     .withNanosecondPrecision()
     .withSynchronizationStrategy(SynchronizationStrategy.LOCK_FREE)
     .build()
-----
+----

asciidoc/src/main/docs/asciidoc/basic/verbose-api.adoc

@@ -1,4 +1,4 @@
-[[verbose-api]]
+[[verbose-api, Verbose/Debug API]]
 === Verbose/Debug API
 Verbose API:: is the API whose intent is in injecting low-level diagnostic information into the results of any interaction with a bucket. Verbose API provides the same functionality as Regular API, with one exception - a result of any method always decorated by `VerboseResult` wrapper.