Skip to content

Commit cd68f34

Browse files
cindytsaicindytsai
committed
[Doc] update api doc.
1 parent 23a5dac commit cd68f34

19 files changed

+271
-420
lines changed

‎doc/Doxyfile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,8 @@ TAB_SIZE = 4
283283
# with the commands \{ and \} for these it is advised to use the version @{ and
284284
# @} or use a double escape (\\{ and \\})
285285

286-
ALIASES =
286+
ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
287+
ALIASES += "endrst=\endverbatim"
287288

288289
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
289290
# only. Doxygen will then generate output that is more tailored for C. For

‎doc/api-doc/index.md‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,33 @@
1-
# Api Doc
1+
# Index
22

3+
## API
4+
5+
```{eval-rst}
6+
.. doxygengroup:: api_yt_initialize
7+
.. doxygengroup:: api_yt_set_Parameters
8+
.. doxygengroup:: api_yt_set_UserParameter
9+
.. doxygengroup:: api_yt_get_FieldsPtr
10+
.. doxygengroup:: api_yt_get_ParticlesPtr
11+
.. doxygengroup:: api_yt_get_GridsPtr
12+
.. doxygengroup:: api_yt_commit
13+
.. doxygengroup:: api_yt_getGridInfo
14+
.. doxygengroup:: api_yt_run_Function
15+
.. doxygengroup:: api_yt_run_InteractiveMode
16+
.. doxygengroup:: api_yt_run_ReloadScript
17+
.. doxygengroup:: api_yt_run_JupyterKernel
18+
.. doxygengroup:: api_yt_free
19+
.. doxygengroup:: api_yt_finalize
20+
```
21+
22+
## Define, Enums, Struct
323
```{eval-rst}
4-
.. doxygenindex::
24+
.. doxygenfile:: libyt.h
25+
.. doxygenfile:: yt_macro.h
26+
.. doxygenfile:: yt_type.h
27+
.. doxygenfile:: yt_type_param_libyt.h
28+
.. doxygenfile:: yt_type_param_yt.h
29+
.. doxygenfile:: yt_type_array.h
30+
.. doxygenfile:: yt_type_field.h
31+
.. doxygenfile:: yt_type_particle.h
32+
.. doxygenfile:: yt_type_grid.h
533
```

‎include/libyt.h‎

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
#ifndef LIBYT_PROJECT_INCLUDE_LIBYT_H_
22
#define LIBYT_PROJECT_INCLUDE_LIBYT_H_
33

4-
/*******************************************************************************
5-
/
6-
/ This is the API header to be included by simulation codes
7-
/
8-
********************************************************************************/
4+
/**
5+
* \file libyt.h
6+
* \brief This is the API header to be included by simulation codes
7+
*/
98

109
#define LIBYT_MAJOR_VERSION 0
1110
#define LIBYT_MINOR_VERSION 1

‎include/yt_type.h‎

Lines changed: 17 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,9 @@
11
#ifndef LIBYT_PROJECT_INCLUDE_YT_TYPE_H_
22
#define LIBYT_PROJECT_INCLUDE_YT_TYPE_H_
33

4-
/*******************************************************************************
5-
/
6-
/ Data types used by libyt
7-
/
8-
********************************************************************************/
4+
/**
5+
* \file yt_type.h
6+
*/
97

108
// enumerate types
119
typedef enum yt_verbose {
@@ -16,20 +14,20 @@ typedef enum yt_verbose {
1614
} yt_verbose;
1715

1816
typedef enum yt_dtype {
19-
YT_FLOAT = 0, // float
20-
YT_DOUBLE, // double
21-
YT_LONGDOUBLE, // long double
22-
YT_CHAR, // char
23-
YT_UCHAR, // unsigned char
24-
YT_SHORT, // short
25-
YT_USHORT, // unsigned short
26-
YT_INT, // int
27-
YT_UINT, // unsigned int
28-
YT_LONG, // long
29-
YT_ULONG, // unsigned long
30-
YT_LONGLONG, // long long
31-
YT_ULONGLONG, // unsigned long long
32-
YT_DTYPE_UNKNOWN
17+
YT_FLOAT = 0, /*!< float */
18+
YT_DOUBLE, /*!< double */
19+
YT_LONGDOUBLE, /*!< long double */
20+
YT_CHAR, /*!< char */
21+
YT_UCHAR, /*!< unsigned char */
22+
YT_SHORT, /*!< short */
23+
YT_USHORT, /*!< unsigned short */
24+
YT_INT, /*!< int */
25+
YT_UINT, /*!< unsigned int */
26+
YT_LONG, /*!< long */
27+
YT_ULONG, /*!< unsigned long */
28+
YT_LONGLONG, /*!< long long */
29+
YT_ULONGLONG, /*!< unsigned long long */
30+
YT_DTYPE_UNKNOWN /*!< unknown data type */
3331
} yt_dtype;
3432

3533
// structures

‎include/yt_type_array.h‎

Lines changed: 8 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -3,36 +3,17 @@
33

44
#include "yt_macro.h"
55

6-
//-------------------------------------------------------------------------------------------------------
7-
// Structure : yt_array
8-
// Description : Data structure to store derived fields and particle attributes generated
9-
// by derived
10-
// functions or get particle attribute functions.
11-
//
12-
// Notes : 1. This struct is used in yt_field data member derived_func.
13-
// 2. This struct is used in yt_particle data member get_par_attr.
14-
//
15-
// Data Member : gid : gid of the field.
16-
// data_length : size of the data_ptr.
17-
// data_ptr : data pointer, where function should fill in the
18-
// required data.
19-
//
20-
// Methods : yt_array : Constructor
21-
//-------------------------------------------------------------------------------------------------------
6+
/**
7+
* \struct yt_array
8+
* \brief Data structure to store data generated by derived function or get particle
9+
* functions
10+
*/
2211
typedef struct yt_array {
23-
long gid;
24-
long data_length;
25-
void* data_ptr;
12+
long gid; /*!< grid id */
13+
long data_length; /*!< length of the data pointer */
14+
void* data_ptr; /*!< data pointer */
2615

2716
#ifdef __cplusplus
28-
//===================================================================================
29-
// Method : yt_array
30-
// Description : Constructor of the structure "yt_array"
31-
//
32-
// Note : Initialize all data members
33-
//
34-
// Parameter : None
35-
//===================================================================================
3617
yt_array() {
3718
gid = LNG_UNDEFINED;
3819
data_length = 0;

‎include/yt_type_field.h‎

Lines changed: 32 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -6,78 +6,42 @@
66
#endif
77
#include "yt_type_array.h"
88

9-
//-------------------------------------------------------------------------------------------------------
10-
// Structure : yt_field
11-
// Description : Data structure to store a field's label and its definition of data
12-
// representation.
13-
//
14-
// Notes : 1. The data representation type will be initialized as "cell-centered".
15-
// 2. The lifetime of field_name and field_type should cover the whole in
16-
// situ process.
17-
// 3. The lifetime of field_unit, field_name_alias, field_display_name
18-
// should cover yt_commit.
19-
// 3. "field_unit", "field_name_alias", "field_display_name", are set
20-
// corresponding to yt
21-
// ( "name", ("units", ["fields", "to", "alias"], "display_name"))
22-
//
23-
// Data Member : const char *field_name : Field name
24-
// const char *field_type : Define type, for now, we have these
25-
// types,
26-
// (1) "cell-centered"
27-
// (2) "face-centered"
28-
// (3) "derived_func"
29-
// yt_dtype field_dtype : Field type of the grid.
30-
// bool contiguous_in_x : true ==> [z][y][x], x address
31-
// alter-first, default value.
32-
// false ==> [x][y][z], z address
33-
// alter-first
34-
// short field_ghost_cell[6] : Number of cell to ignore at the
35-
// beginning and the end of each
36-
// dimension.
37-
// The dimensions are in the point of
38-
// view of the field data, it has
39-
// nothing to do with x, y, z
40-
// coordinates.
41-
//
42-
// const char *field_unit : Set field_unit if needed.
43-
// int num_field_name_alias : Set field to alias names, number of
44-
// the aliases. const char **field_name_alias : Aliases. const char
45-
// *field_display_name : Set display name on the figure, if not set, yt
46-
// will use field
47-
// name as display name.
48-
//
49-
// (func pointer) derived_func : pointer to function that has
50-
// prototype
51-
// void (const int, const long*, const
52-
// char*, yt_array*).
53-
//
54-
// Method : yt_field : Constructor
55-
//-------------------------------------------------------------------------------------------------------
9+
/**
10+
* \struct yt_field
11+
* \brief Data structure to store a field's label and its definition of data
12+
* representation.
13+
* \details
14+
* 1. `field_unit`, `field_name_alias`, `field_display_name`, are set corresponding to yt
15+
* frontend `( "name", ("units", ["fields", "to", "alias"], "display_name"))`.
16+
*
17+
* \rst
18+
* .. caution::
19+
* The lifetime of ``field_name`` and ``field_type`` should cover the whole in
20+
* situ process.
21+
*
22+
* The lifetime of ``field_unit``, ``field_name_alias``, ``field_display_name``
23+
* should cover \ref yt_commit.
24+
* \endrst
25+
*/
5626
typedef struct yt_field {
57-
const char* field_name;
58-
const char* field_type;
59-
yt_dtype field_dtype;
60-
bool contiguous_in_x;
61-
short field_ghost_cell[6];
62-
const char* field_unit;
63-
int num_field_name_alias;
64-
const char** field_name_alias;
65-
const char* field_display_name;
27+
const char* field_name; /*!< Field name */
28+
const char* field_type; /*!< Define type
29+
* (`"cell-centered"`, `"face-centered"`,
30+
* `"derived_func"`) */
31+
yt_dtype field_dtype; /*!< Field data type */
32+
bool contiguous_in_x; /*!< true for x address alter-first (`[z][y][x]`);
33+
* false for z address alter-first (`[x][y][z]`)*/
34+
short field_ghost_cell[6]; /*!< Number of cell to ignore at the beginning and the
35+
* end of each dimension of a data pointer. */
36+
const char* field_unit; /*!< Field unit */
37+
int num_field_name_alias; /*!< Number of field name alias */
38+
const char** field_name_alias; /*!< A list of field name alias */
39+
const char* field_display_name; /*!< Field display name */
40+
41+
/** Derived function */
6642
void (*derived_func)(const int, const long*, const char*, yt_array*);
6743

6844
#ifdef __cplusplus
69-
//=======================================================================================================
70-
// Method : yt_field
71-
// Description : Constructor of the structure "yt_field"
72-
//
73-
// Note : 1. Initialize field_type as "cell-centered"
74-
// 2. Initialize field_unit as "". If it is not set by user, then yt will
75-
// use the particle
76-
// unit set at yt frontend. If there still isn't one, then it will use
77-
// "".
78-
//
79-
// Parameter : None
80-
// ======================================================================================================
8145
yt_field() {
8246
field_name = nullptr;
8347
field_type = "cell-centered";

0 commit comments

Comments
 (0)