Skip to content

Commit b30fb43

Browse files
jacobwilliamsjacobwilliams
committed
additional documentation updates for FORD.
1 parent 017cf0d commit b30fb43

File tree

2 files changed

+72
-89
lines changed

2 files changed

+72
-89
lines changed

‎json-fortran.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@ summary: JSON-FORTRAN -- A Fortran 2008 JSON API
66
author: Jacob Williams
77
github: https://github.com/jacobwilliams
88
predocmark_alt: >
9-
docmark_alt: <
9+
predocmark: <
10+
docmark_alt:
11+
docmark: !
1012
exclude_dir: tests
1113
exclude_dir: introspection
1214
display: public

‎src/json_module.F90

Lines changed: 69 additions & 88 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,37 @@
11
!*****************************************************************************************
2-
!>author: Jacob Williams
2+
!> author: Jacob Williams
3+
! license: BSD
34
!
45
! JSON-FORTRAN: A Fortran 2008 JSON (JavaScript Object Notation) API.
56
!
6-
!# See also
7-
! * [json-fortran development site](http://github.com/jacobwilliams/json-fortran)
8-
! * [json-fortran online documentation](http://jacobwilliams.github.io/json-fortran)
9-
! * [JSON website](http://www.json.org/)
10-
! * [JSON validator](http://jsonlint.com/)
7+
! This module provides an interface for reading and writing JSON files.
8+
!
9+
!@note ```USE_UCS4``` is an optional preprocessor flag.
10+
! When present, Unicode support is enabled. Note that this
11+
! is currently only supported with the gfortran compiler.
12+
! Example: ```gfortran -DUSE_UCS4 ... ```
13+
#ifdef USE_UCS4
14+
! The documentation given here assumes ```USE_UCS4``` **is** defined.
15+
#else
16+
! The documentation given here assumes ```USE_UCS4``` **is not** defined.
17+
#endif
18+
!
19+
!@note ```CK``` and ```CDK``` are the json-fortran character kind and json-fortran default
20+
! character kind respectively. Client code must ensure characters of kind=CK
21+
! are used for all character variables and strings passed to the json-fortran
22+
! library *EXCEPT* for file names which must be of ```'DEFAULT'``` character kind,
23+
! provided here as ```CDK```. In particular, any: json path, character or string, or
24+
! object name passed to the json-fortran library *MUST* be of type ```CK```.
1125
!
1226
!# License
1327
!
14-
! json-fortran License:
28+
! **json-fortran License:**
1529
!
1630
! JSON-FORTRAN: A Fortran 2008 JSON API
1731
!
1832
! http://github.com/jacobwilliams/json-fortran
1933
!
20-
! Copyright (c) 2014, Jacob Williams
34+
! Copyright (c) 2014-2015, Jacob Williams
2135
!
2236
! All rights reserved.
2337
!
@@ -41,9 +55,7 @@
4155
! (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
4256
! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
4357
!
44-
! Original FSON License:
45-
!
46-
! http://github.com/josephalevin/fson
58+
! **Original FSON License:**
4759
!
4860
! Copyright (c) 2012 Joseph A. Levin
4961
!
@@ -73,6 +85,12 @@
7385
! Various Fortran 2003/2008 features are now used
7486
! (e.g., allocatable strings, newunit, generic, class, and abstract interface).
7587
! * Development continues at: [Github](http://github.com/jacobwilliams/json-fortran)
88+
!
89+
!# See also
90+
! * [json-fortran development site](http://github.com/jacobwilliams/json-fortran)
91+
! * [json-fortran online documentation](http://jacobwilliams.github.io/json-fortran)
92+
! * [JSON website](http://www.json.org/)
93+
! * [JSON validator](http://jsonlint.com/)
7694

7795
module json_module
7896

@@ -82,17 +100,6 @@ module json_module
82100

83101
private
84102

85-
!*********************************************************
86-
!
87-
! USE_UCS4 is an optional preprocessor flag.
88-
! When present, Unicode support is enabled.
89-
!
90-
! USAGE
91-
! When compiling:
92-
! * gfortran -DUSE_UCS4 ...
93-
!
94-
!*********************************************************
95-
96103
integer,parameter :: RK = real64 !! Default real kind [8 bytes]
97104

98105
integer,parameter :: IK = int32 !! Default integer kind [4 bytes].
@@ -101,21 +108,7 @@ module json_module
101108
!>
102109
! Processor dependendant 'DEFAULT' character kind.
103110
! This is 1 byte for the Intel and Gfortran compilers.
104-
!
105-
!# Notes
106-
! CK and CDK are the json-fortran character kind and json-fortran default
107-
! character kind respectively. Client code must ensure characters of kind=CK
108-
! are used for all character variables and strings passed to the json-fortran
109-
! library *EXCEPT* for file names which must be of 'DEFAULT' character kind,
110-
! provided here as CDK. In particular, any:
111-
! * file name
112-
! * format statement
113-
! * file path
114-
! passed to the json-fortran library *MUST* be of type CDK. This
115-
! will be the case for all string literals nor prepended with CK_ and only
116-
! if ISO 10646 is supported and enabled, will strings of kind CK be different
117-
! than CDK
118-
!
111+
119112
integer,parameter,public :: CDK = selected_char_kind('DEFAULT')
120113
!*********************************************************
121114

@@ -152,17 +145,6 @@ module json_module
152145
! Currently only gfortran >= 4.9.2 will correctly support
153146
! UCS4 which is stored in 4 bytes.
154147
! (and perhaps others).
155-
!
156-
!# Notes
157-
! CK and CDK are the json-fortran character kind and json-fortran default
158-
! character kind respectively. Client code must ensure characters of kind=CK
159-
! are used for all character variables and strings passed to the json-fortran
160-
! library *EXCEPT* for file names which must be of 'DEFAULT' character kind,
161-
! provided here as JDCK. In particular, any:
162-
! * json path
163-
! * character or string
164-
! * object name
165-
! passed to the json-fortran library *MUST* be of type CK.
166148

167149
integer,parameter,public :: CK = selected_char_kind(json_fortran_string_kind)
168150
!*********************************************************
@@ -841,8 +823,10 @@ end subroutine array_callback_func
841823
rp_addl_safety
842824

843825
!Get the number of possible digits in the exponent when using decimal number system
826+
integer(IK),parameter :: maxexp = maxexponent(1.0_RK)
827+
integer(IK),parameter :: minexp = minexponent(1.0_RK)
844828
integer(IK),parameter :: real_exponent_digits = floor( 1 + log10( &
845-
real(max(maxexponent(1.0_RK),abs(minexponent(1.0_RK))),&
829+
real(max(maxexp,abs(maxexp)),&
846830
kind=RK) ) )
847831

848832
!6 = sign + leading 0 + decimal + 'E' + exponent sign + 1 extra
@@ -884,7 +868,7 @@ end subroutine array_callback_func
884868
!*****************************************************************************************
885869
!> author: Jacob Williams
886870
!
887-
! Destroy the [[json_value]] type.
871+
! Destroy the data within a [[json_value]], and rest type to json_unknown.
888872

889873
subroutine destroy_json_data(d)
890874

@@ -964,7 +948,7 @@ subroutine json_file_load(me, filename, unit)
964948

965949
class(json_file),intent(inout) :: me
966950
character(kind=CDK,len=*),intent(in) :: filename !! the filename to open
967-
integer(IK),intent(in),optional :: unit !! the unit to use
951+
integer(IK),intent(in),optional :: unit !! the unit number to use
968952

969953
call json_parse(file=filename, p=me%p, unit=unit)
970954

@@ -2632,8 +2616,8 @@ subroutine wrap_json_value_add_integer(me, name, val)
26322616
implicit none
26332617

26342618
type(json_value),pointer :: me
2635-
character(kind=CDK,len=*),intent(in) :: name
2636-
integer(IK),intent(in) :: val
2619+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2620+
integer(IK),intent(in) :: val !! value
26372621

26382622
call json_value_add_integer(me, to_unicode(name), val)
26392623

@@ -2654,8 +2638,8 @@ subroutine json_value_add_integer_vec(me, name, val)
26542638
implicit none
26552639

26562640
type(json_value),pointer :: me
2657-
character(kind=CK,len=*),intent(in) :: name
2658-
integer(IK),dimension(:),intent(in) :: val
2641+
character(kind=CK,len=*),intent(in) :: name !! name of the variable
2642+
integer(IK),dimension(:),intent(in) :: val !! value
26592643

26602644
type(json_value),pointer :: var
26612645
integer(IK) :: i !counter
@@ -2687,8 +2671,8 @@ subroutine wrap_json_value_add_integer_vec(me, name, val)
26872671
implicit none
26882672

26892673
type(json_value),pointer :: me
2690-
character(kind=CDK,len=*),intent(in) :: name
2691-
integer(IK),dimension(:),intent(in) :: val
2674+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2675+
integer(IK),dimension(:),intent(in) :: val !! value
26922676

26932677
call json_value_add_integer_vec(me, to_unicode(name), val)
26942678

@@ -2709,8 +2693,8 @@ subroutine json_value_add_logical(me, name, val)
27092693
implicit none
27102694

27112695
type(json_value),pointer :: me
2712-
character(kind=CK,len=*),intent(in) :: name
2713-
logical(LK),intent(in) :: val
2696+
character(kind=CK,len=*),intent(in) :: name !! name of the variable
2697+
logical(LK),intent(in) :: val !! value
27142698

27152699
type(json_value),pointer :: var
27162700

@@ -2736,8 +2720,8 @@ subroutine wrap_json_value_add_logical(me, name, val)
27362720
implicit none
27372721

27382722
type(json_value),pointer :: me
2739-
character(kind=CDK,len=*),intent(in) :: name
2740-
logical(LK),intent(in) :: val
2723+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2724+
logical(LK),intent(in) :: val !! value
27412725

27422726
call json_value_add_logical(me, to_unicode(name), val)
27432727

@@ -2758,8 +2742,8 @@ subroutine json_value_add_logical_vec(me, name, val)
27582742
implicit none
27592743

27602744
type(json_value),pointer :: me
2761-
character(kind=CK,len=*),intent(in) :: name
2762-
logical(LK),dimension(:),intent(in) :: val
2745+
character(kind=CK,len=*),intent(in) :: name !! name of the vector
2746+
logical(LK),dimension(:),intent(in) :: val !! value
27632747

27642748
type(json_value),pointer :: var
27652749
integer(IK) :: i !counter
@@ -2791,8 +2775,8 @@ subroutine wrap_json_value_add_logical_vec(me, name, val)
27912775
implicit none
27922776

27932777
type(json_value),pointer :: me
2794-
character(kind=CDK,len=*),intent(in) :: name
2795-
logical(LK),dimension(:),intent(in) :: val
2778+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2779+
logical(LK),dimension(:),intent(in) :: val !! value
27962780

27972781
call json_value_add_logical_vec(me, to_unicode(name), val)
27982782

@@ -2813,8 +2797,8 @@ subroutine json_value_add_string(me, name, val)
28132797
implicit none
28142798

28152799
type(json_value),pointer :: me
2816-
character(kind=CK,len=*),intent(in) :: name
2817-
character(kind=CK,len=*),intent(in) :: val
2800+
character(kind=CK,len=*),intent(in) :: name !! name of the variable
2801+
character(kind=CK,len=*),intent(in) :: val !! value
28182802

28192803
type(json_value),pointer :: var
28202804
character(kind=CK,len=:),allocatable :: str
@@ -2844,8 +2828,8 @@ subroutine wrap_json_value_add_string(me, name, val)
28442828
implicit none
28452829

28462830
type(json_value),pointer :: me
2847-
character(kind=CDK,len=*),intent(in) :: name
2848-
character(kind=CDK,len=*),intent(in) :: val
2831+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2832+
character(kind=CDK,len=*),intent(in) :: val !! value
28492833

28502834
call json_value_add_string(me, to_unicode(name), to_unicode(val))
28512835

@@ -2861,8 +2845,8 @@ subroutine json_value_add_string_name_ascii(me, name, val)
28612845
implicit none
28622846

28632847
type(json_value),pointer :: me
2864-
character(kind=CDK,len=*),intent(in) :: name
2865-
character(kind=CK, len=*),intent(in) :: val
2848+
character(kind=CDK,len=*),intent(in) :: name !! name of the variable
2849+
character(kind=CK, len=*),intent(in) :: val !! value
28662850

28672851
call json_value_add_string(me, to_unicode(name), val)
28682852

@@ -2878,8 +2862,8 @@ subroutine json_value_add_string_val_ascii(me, name, val)
28782862
implicit none
28792863

28802864
type(json_value),pointer :: me
2881-
character(kind=CK, len=*),intent(in) :: name
2882-
character(kind=CDK,len=*),intent(in) :: val
2865+
character(kind=CK, len=*),intent(in) :: name !! name of the variable
2866+
character(kind=CDK,len=*),intent(in) :: val !! value
28832867

28842868
call json_value_add_string(me, name, to_unicode(val))
28852869

@@ -5999,35 +5983,33 @@ end subroutine parse_array
59995983
!
60005984
!# History
60015985
! * Jacob Williams : 6/16/2014 : Added hex validation.
6002-
!
60035986

60045987
subroutine parse_string(unit, str, string)
60055988

60065989
implicit none
60075990

6008-
integer(IK), intent(in) :: unit !! file unit number (if parsing from a file)
6009-
character(kind=CK,len=*),intent(in) :: str !! JSON string (if parsing from a string)
6010-
character(kind=CK,len=:),allocatable,intent(out) :: string
5991+
integer(IK),intent(in) :: unit !! file unit number (if parsing from a file)
5992+
character(kind=CK,len=*),intent(in) :: str !! JSON string (if parsing from a string)
5993+
character(kind=CK,len=:),allocatable,intent(out) :: string
60115994

60125995
logical(LK) :: eof, is_hex, escape
60135996
character(kind=CK,len=1) :: c, last
60145997
character(kind=CK,len=4) :: hex
60155998
integer(IK) :: i
6016-
6017-
!to speed up by reducing the number of character string reallocations:
6018-
integer(IK) :: ip !index to put next character
5999+
integer(IK) :: ip !! index to put next character,
6000+
!! to speed up by reducing the number of character string reallocations.
60196001

60206002
!at least return a blank string if there is a problem:
60216003
string = repeat(space, chunk_size)
60226004

60236005
if (.not. exception_thrown) then
60246006

60256007
!initialize:
6026-
ip = 1
6027-
last = space
6008+
ip = 1
6009+
last = space
60286010
is_hex = .false.
60296011
escape = .false.
6030-
i = 0
6012+
i = 0
60316013

60326014
do
60336015

@@ -6113,9 +6095,9 @@ subroutine parse_for_chars(unit, str, chars)
61136095

61146096
implicit none
61156097

6116-
integer(IK), intent(in) :: unit !! file unit number (if parsing from a file)
6117-
character(kind=CK,len=*),intent(in) :: str !! JSON string (if parsing from a string)
6118-
character(kind=CK,len=*), intent(in) :: chars
6098+
integer(IK),intent(in) :: unit !! file unit number (if parsing from a file)
6099+
character(kind=CK,len=*),intent(in) :: str !! JSON string (if parsing from a string)
6100+
character(kind=CK,len=*),intent(in) :: chars !! the string to check for.
61196101

61206102
integer(IK) :: i, length
61216103
logical(LK) :: eof
@@ -6371,7 +6353,6 @@ end function pop_char
63716353
!
63726354
!# History
63736355
! * Jacob Williams : 5/3/2015 : replaced original version of this routine.
6374-
!
63756356

63766357
subroutine push_char(c)
63776358

@@ -6482,7 +6463,7 @@ subroutine compact_real_string(str)
64826463

64836464
implicit none
64846465

6485-
character(kind=CK,len=*),intent(inout) :: str
6466+
character(kind=CK,len=*),intent(inout) :: str !! string representation of a real number.
64866467

64876468
character(kind=CK,len=len(str)) :: significand, expnt
64886469
character(kind=CK,len=2) :: separator

0 commit comments

Comments
 (0)