Skip to content

JSON structure

Jump to bottom
RookieHPC edited this page May 20, 2022 · 4 revisions

-- WIKI CURRENTLY IN WRITING --

I) Documentation entry

I.1) Root level

JSON attribute Datatype Description Example value
Type String The type of the entry. Must be set to "Documentation" in this case. "Documentation"
Technology String The technology concerned; MPI or OpenMP only so far, although additional technologies will become available in future. "MPI"
Name String The name that will appear on the webpages. "MPI_Comm_size"
DirectoryName String The name of the directory in which the corresponding data.json file is stored. Must be only lowercase letters. "mpi_comm_size"
SharedDescription Boolean Set to true if the documentation entry has the same description regardless of the programming language used, in which only one description will need to be provided. Otherwise, one description per language will be required. true
Description String If SharedDescription is set to true, this attribute is required; it will contain the description to display regardless of the technology selected. If SharedDescription is set to false, this attribute must not exist. "MPI_Comm_size does this, it does that..."
Categories Array of strings The technology categories in which this documentation entry can be put. ["Non-blocking", "Collective"]
Languages Array of objects The documentation entries, one per language. See section 2.2

I.1.a) Example with a shared documentation

{
    "Type":"Documentation",
    "Name":"MPI_Comm_size",
    "DirectoryName":"mpi_comm_size",
    "SharedDescription":true,
    "Description":"MPI_Comm_size gets the number of MPI processes in the communicator given."
    "Categories":["Topology"]
    "Languages": -- See section I.2) --
}

I.1.b) Example with no shared documentation

{
    "Type":"Documentation",
    "Name":"MPI_Datatype",
    "DirectoryName":"mpi_datatype",
    "SharedDescription":false,
    "Categories":["Datatypes"]
    "Languages": -- See section I.2) --
}

I.2) "Languages" array of objects

Each documentation entry has a "Languages" attribute containing an array of objects, each representing the documentation entry for a given language, whose structure is as follows:

JSON Attribute Datatype Description Value
"Language" String The language considered; "C", "FORTRAN-90" and "FORTRAN-2008" only so far, although additional languages will be appended to the list in future. "C"
"Parameters" Array of objects Will be used to generate the "Parameters" section of the page, as well as producing the prototype code snippet when application. If the documentation entry is a function or subroutine, even if it does not accept any parameter, this attribute must be used (as an empty array if no parameter is accepted). - Too long -
"Return" Object If the documentation entry is a function and thus returns a value, this attribute must exist. It will be used to produce the "Return" section of the webpage. {"Name":"comm","Description":"The communicator considered","Type":"MPI_Comm"}

I.2.a) Example with a shared documentation

(Following up on the MPI_Comm_size example given earlier)

[
    {
        "Language":"C",
        "Parameters": -- See section I.3) --,
        "Return":"MPI_SUCCESS if the routine completed successfully."
    },
    {
        "Language":"FORTRAN-90",
        "Parameters": -- See section I.3) --,
    },
    {
        "Language":"FORTRAN-2008",
        "Parameters": -- See section I.3) --,
    }
]

I.2.b) Example with no shared documentation

(Following up on the MPI_Datatype example given earlier)

[
    {
        "Language":"C",
        "Description":"In C, the MPI_Datatype is of type MPI_Datatype. The list of possible MPI_Datatypes is MPI_INT, MPI_DOUBLE, MPI_C_BOOL etc...",
        "Parameters": -- See section I.3) --,
        "Return":"MPI_SUCCESS if the routine completed successfully."
    },
    {
        "Language":"FORTRAN-90",
        "Description":"In FORTRAN-90, the MPI_Datatype is of type INTEGER. The list of possible MPI_Datatypes is MPI_INTEGER, MPI_REAL, etc...",
        "Parameters": -- See section I.3) --,
    },
    {
        "Language":"FORTRAN-2008",
        "Description":"In FORTRAN-2008, the MPI_Datatype is of type TYPE(MPI_Comm). The list of possible MPI_Datatypes is MPI_INTEGER, MPI_REAL, etc...",
        "Parameters": -- See section I.3) --,
    }
]

I.3) "Parameters" array of object

Functions or subroutines that do accept parameters must provide an array of objects, each representing a parameter, whose structure is as follows:

JSON attribute Type Description Example value
"Name" String The name of the parameter. "my_comm_size"
"Description" String The description of the parameter role. "The variable in which store the size of the communicator."
"Type" String The type of the parameter. "int"
"Optional" Boolean Optional attribute to use only with programming languages that allow optional parameters such as FORTRAN-2008, it indicates whether the parameter is optional. true
"Intent" String Optional attribute to use only with programming languages that support parameter intent such as FORTRAN-2008, it indicates the access pattern to the parameter. Values are "IN" for read-only, "OUT" for write-only and "INOUT" for read-write. "IN"

I.3.a) Example without optional parameters or intent

*(Following up on the MPI_Comm_size given earlier, in C)

[
    {
        "Name":"comm",
        "Description":"The MPI communicator to query.",
        "Type":"MPI_Comm"
    },
    {
        "Name":"size",
        "Description":"The variable in which store the size of the communicator.",
        "Type":"int*"
    }
]

I.3.b) Example with optional parameters and intent

*(Following up on the MPI_Comm_size given earlier, in FORTRAN-2008)

[
    {
        "Name": "comm",
        "Description": "The communicator to query.",
        "Type": "TYPE(MPI_Comm)",
        "Optional": false,
        "Intent": "IN"
    },
    {
        "Name": "size",
        "Description": "The variable in which store the size found.",
        "Type": "INTEGER",
        "Optional": false,
        "Intent": "OUT"
    },
    {
        "Name": "ierror",
        "Description": "The error code of the size retrieval.",
        "Type": "INTEGER",
        "Optional": true,
        "Intent": "OUT"
    }
]

II.4) Full examples

II.4.a) Full example with shared description

{
    "Type":"Documentation",
    "Name":"MPI_Comm_size",
    "DirectoryName":"mpi_comm_size",
    "SharedDescription":true,
    "Description":"MPI_Comm_size gets the number of MPI processes in the communicator given."
    "Categories":["Topology"]
    "Languages": [
        {
            "Language":"C",
            "Parameters": [
                {
                    "Name":"comm",
                    "Description":"The MPI communicator to query.",
                    "Type":"MPI_Comm"
                },
                {
                    "Name":"size",
                    "Description":"The variable in which store the size of the communicator.",
                    "Type":"int*"
                }
            ],
            "Return":"MPI_SUCCESS if the routine completed successfully."
        },
        {
            "Language":"FORTRAN-90",
            "Parameters": [
                {
                    "Name":"comm",
                    "Description":"The MPI communicator to query.",
                    "Type":"INTEGER"
                },
                {
                    "Name":"size",
                    "Description":"The variable in which store the size of the communicator.",
                    "Type":"INTEGER"
                }
            ]
        },
        {
            "Language":"FORTRAN-2008",
            "Parameters": [
                {
                    "Name": "comm",
                    "Description": "The communicator to query.",
                    "Type": "TYPE(MPI_Comm)",
                    "Optional": false,
                    "Intent": "IN"
                },
                {
                    "Name": "size",
                    "Description": "The variable in which store the size found.",
                    "Type": "INTEGER",
                    "Optional": false,
                    "Intent": "OUT"
                },
                {
                    "Name": "ierror",
                    "Description": "The error code of the size retrieval.",
                    "Type": "INTEGER",
                    "Optional": true,
                    "Intent": "OUT"
                }
            ],
        }
    ]
}
Clone this wiki locally