Clarify the general purpose of the belgif-rest-problem library (#26)

Author: jpraet

README.md

@@ -4,7 +4,15 @@
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=belgif_rest-problem-java&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=belgif_rest-problem-java)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=belgif_rest-problem-java&metric=coverage)](https://sonarcloud.io/summary/new_code?id=belgif_rest-problem-java)
 
-Java library for RFC 9457 Problems with support for standard problem types of the Belgif REST guide (https://www.belgif.be/specification/rest/api-guide/#error-handling).
+Java library for [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) Problems with support for standard problem types of
+the [Belgif REST guide](https://www.belgif.be/specification/rest/api-guide/#error-handling).
+
+With this library, RFC 9457 Problems can be treated as standard java exceptions:
+
+* the server side can throw `io.github.belgif.rest.problem.api.Problem` exceptions (or subclasses), which are
+  transparently converted to RFC 9457 compliant "application/problem+json" responses
+* the client side can catch `io.github.belgif.rest.problem.api.Problem` exceptions (or subclasses), which are
+  transparently thrown when an RFC 9457 compliant "application/problem+json" response is received
 
 ## build process
 

src/main/asciidoc/index.adoc

@@ -11,6 +11,21 @@
 
 = belgif-rest-problem
 
+== Context
+
+Java library for working with https://www.belgif.be/specification/rest/api-guide/#error-handling[RFC 9457 standardized Belgif problems].
+
+With this library, RFC 9457 Problems can be treated as standard java exceptions:
+
+* the server side can throw `io.github.belgif.rest.problem.api.Problem` exceptions (or subclasses), which are transparently converted to RFC 9457 compliant "application/problem+json" responses
+* the client side can catch `io.github.belgif.rest.problem.api.Problem` exceptions (or subclasses), which are transparently thrown when an RFC 9457 compliant "application/problem+json" response is received
+
+The library consists of these modules:
+
+* <<belgif-rest-problem>>: library for RFC 9457 standardized Belgif problems
+* <<belgif-rest-problem-java-ee>>: Java EE / Jakarta EE integration for belgif-rest-problem
+* <<belgif-rest-problem-spring>>: Spring Boot integration for belgif-rest-problem
+
 == Release notes
 
 === Version 0.2
@@ -33,16 +48,6 @@
 
 Initial release under Belgif organization.
 
-== Context
-
-Java library for working with https://www.belgif.be/specification/rest/api-guide/#error-handling[RFC 9457 standardized Belgif problems].
-
-The library consists of these modules:
-
-* <<belgif-rest-problem>>: library for RFC 9457 standardized Belgif problems
-* <<belgif-rest-problem-java-ee>>: Java EE / Jakarta EE integration for belgif-rest-problem
-* <<belgif-rest-problem-spring>>: Spring Boot integration for belgif-rest-problem
-
 [[belgif-rest-problem]]
 == belgif-rest-problem