Apply restructring of specs from review

Co-authored-by: Jeremie Vandenplas <[email protected]>

Author: awvwgk

doc/specs/stdlib_ascii.md

@@ -35,8 +35,7 @@ Converts input character variable to all lowercase.
 #### Syntax
 
 ```f90
-res = to_lower("HELLO!")
-! res == "hello!"
+res = [stdlib_asciii(module):to_lower(function)]](string)
 ```
 
 #### Class
@@ -51,6 +50,15 @@ Pure function.
 
 The result is an intrinsic character type of the same length as `string`.
 
+#### Example
+
+```fortran
+program demo_to_lower
+    use stdlib_ascii, only : to_lower
+    implicit none
+    print'(a)', to_lower("HELLo!") ! returns "hello!"
+ end program demo_to_lower
+``` 
 
 ### `to_upper`
 
@@ -64,9 +72,8 @@ Converts input character variable to all uppercase.
 
 #### Syntax
 
-```
-res = to_upper("hello!")
-! res == "HELLO!"
+```fortran
+res = [[stdlib_ascii(module):to_upper(function)]](string)
 ```
 
 #### Class
@@ -81,6 +88,15 @@ Pure function.
 
 The result is an intrinsic character type of the same length as `string`.
 
+#### Example
+
+```fortran
+program demo_to_upper
+    use stdlib_ascii, only : to_upper
+    implicit none
+    print'(a)', to_upper("hello!") ! returns "HELLO!"
+ end program demo_to_upper
+``` 
 
 ### `to_title`
 
@@ -90,18 +106,14 @@ Experimental
 
 #### Description
 
-Returns capitalized version of input character variable.
-The first alphanumeric character is capitalized.
+Returns a capitalized version of an input character variable.
+Only the first alphanumeric character is capitalized.
+All following characters will become lowercase.
 
 #### Syntax
 
 ```
-res = to_title("hello!")
-! res == "Hello!"
-res = to_title("'enquoted'")
-! res == "'Enquoted'"
-res = to_title("1st")
-! res == "1st"
+res = [[stdlib_ascii(module):to_title(interface)]](string)
 ```
 
 #### Class
@@ -116,6 +128,17 @@ Pure function.
 
 The result is an intrinsic character type of the same length as `string`.
 
+#### Example
+
+```fortran
+program demo_to_title
+    use stdlib_ascii, only : to_title
+    implicit none
+    print*, to_title("hello!") ! returns "Hello!"
+    print*, to_title("'enquoted'") ! returns "'Enquoted'"
+    print*, to_title("1st")  ! returns "1st"
+ end program demo_to_title
+``` 
 
 ### `reverse`
 
@@ -130,10 +153,7 @@ Reverses the order of all characters in the input character type.
 #### Syntax
 
 ```f90
-res = reverse("Hello, World!")
-! res == "!dlroW ,olleH"
-res = reverse(res)
-! res == "Hello, World!"
+res = [[stdlib_ascii(module):reverse(function)]](string)
 ```
 
 #### Class
@@ -147,3 +167,12 @@ Pure function.
 #### Result value
 
 The result is an intrinsic character type of the same length as `string`.
+
+#### Example
+
+```fortran
+program demo_reverse
+    use stdlib_ascii, only : reverse
+    implicit none
+    print'(a)', reverse("Hello, World!") ! returns "!dlroW ,olleH"
+end program demo_reverse