Skip to content

Commit 7656bd5

Browse files
jkeiserjkeiser
committed
Generate API docs at /api/docs
1 parent 6ee3318 commit 7656bd5

File tree

8 files changed

+2669
-65
lines changed

8 files changed

+2669
-65
lines changed

‎.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,9 @@ objs
119119
/tools/jsonstats
120120
/tools/minify
121121

122+
# Don't check in generated API docs
123+
/doc/api
124+
122125
# Don't check in generated examples
123126
/jsonexamples/generated
124127

‎Doxyfile

Lines changed: 2578 additions & 0 deletions
Large diffs are not rendered by default.

‎Makefile

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -290,3 +290,6 @@ clean:
290290

291291
cleandist:
292292
rm -f submodules $(EXTRAOBJECTS) $(MAINEXECUTABLES) $(EXTRA_EXECUTABLES) $(TESTEXECUTABLES) $(COMPARISONEXECUTABLES) $(SUPPLEMENTARYEXECUTABLES)
293+
294+
doc/api: $(HEADERS)
295+
doxygen

‎include/simdjson.h

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
#ifndef SIMDJSON_H
22
#define SIMDJSON_H
33

4+
/**
5+
* @mainpage
6+
*
7+
* Check the [README.md](https://github.com/lemire/simdjson/blob/master/README.md#simdjson--parsing-gigabytes-of-json-per-second).
8+
*/
9+
410
#include "simdjson/compiler_check.h"
511

612
// Public API

‎include/simdjson/document.h

Lines changed: 65 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -97,22 +97,24 @@ class document {
9797
*
9898
* The parser will allocate capacity as needed.
9999
*/
100-
document() noexcept=default;
101-
~document() noexcept=default;
100+
document() noexcept = default;
101+
~document() noexcept = default;
102102

103103
/**
104104
* Take another document's buffers.
105105
*
106106
* @param other The document to take. Its capacity is zeroed and it is invalidated.
107107
*/
108108
document(document &&other) noexcept = default;
109+
/** @private */
109110
document(const document &) = delete; // Disallow copying
110111
/**
111112
* Take another document's buffers.
112113
*
113114
* @param other The document to take. Its capacity is zeroed.
114115
*/
115116
document &operator=(document &&other) noexcept = default;
117+
/** @private */
116118
document &operator=(const document &) = delete; // Disallow copying
117119

118120
/**
@@ -121,15 +123,19 @@ class document {
121123
element root() const noexcept;
122124

123125
/**
124-
* Dump the raw tape for debugging.
126+
* @private Dump the raw tape for debugging.
125127
*
126128
* @param os the stream to output to.
127129
* @return false if the tape is likely wrong (e.g., you did not parse a valid JSON).
128130
*/
129131
bool dump_raw_tape(std::ostream &os) const noexcept;
130132

131133
std::unique_ptr<uint64_t[]> tape;
132-
std::unique_ptr<uint8_t[]> string_buf;// should be at least byte_capacity
134+
/** @private String values.
135+
*
136+
* Should be at least byte_capacity.
137+
*/
138+
std::unique_ptr<uint8_t[]> string_buf;
133139

134140
private:
135141
inline error_code set_capacity(size_t len) noexcept;
@@ -592,6 +598,7 @@ class parser {
592598
* DEFAULT_MAX_DEPTH.
593599
*/
594600
really_inline parser(size_t max_capacity = SIMDJSON_MAXSIZE_BYTES, size_t max_depth = DEFAULT_MAX_DEPTH) noexcept;
601+
/** Deallocate the JSON parser. */
595602
~parser()=default;
596603

597604
/**
@@ -600,14 +607,14 @@ class parser {
600607
* @param other The parser to take. Its capacity is zeroed.
601608
*/
602609
parser(parser &&other) = default;
603-
parser(const parser &) = delete; // Disallow copying
610+
parser(const parser &) = delete; ///< @private Disallow copying
604611
/**
605612
* Take another parser's buffers and state.
606613
*
607614
* @param other The parser to take. Its capacity is zeroed.
608615
*/
609616
parser &operator=(parser &&other) = default;
610-
parser &operator=(const parser &) = delete; // Disallow copying
617+
parser &operator=(const parser &) = delete; ///< @private Disallow copying
611618

612619
/**
613620
* Load a JSON document from a file and return a reference to it.
@@ -1147,34 +1154,35 @@ class parser {
11471154
/** @deprecated Use simdjson_error instead */
11481155
using InvalidJSON = simdjson_error;
11491156

1150-
// Next location to write to in the tape
1157+
/** @private Next location to write to in the tape */
11511158
uint32_t current_loc{0};
11521159

1153-
// structural indices passed from stage 1 to stage 2
1160+
/** @private Number of structural indices passed from stage 1 to stage 2 */
11541161
uint32_t n_structural_indexes{0};
1162+
/** @private Structural indices passed from stage 1 to stage 2 */
11551163
std::unique_ptr<uint32_t[]> structural_indexes;
11561164

1157-
// location and return address of each open { or [
1165+
/** @private Tape location of each open { or [ */
11581166
std::unique_ptr<uint32_t[]> containing_scope_offset;
11591167
#ifdef SIMDJSON_USE_COMPUTED_GOTO
1168+
/** @private Return address of each open { or [ */
11601169
std::unique_ptr<void*[]> ret_address;
11611170
#else
1171+
/** @private Return address of each open { or [ */
11621172
std::unique_ptr<char[]> ret_address;
11631173
#endif
11641174

1165-
// Next place to write a string
1175+
/** @private Next write location in the string buf for stage 2 parsing */
11661176
uint8_t *current_string_buf_loc;
11671177

1178+
/** @deprecated Use `if (parser.parse(...).error)` instead */
11681179
bool valid{false};
1180+
/** @deprecated Use `parser.parse(...).error` instead */
11691181
error_code error{UNINITIALIZED};
11701182

1171-
// Document we're writing to
1183+
/** @deprecated Use `parser.parse(...).doc` instead */
11721184
document doc;
11731185

1174-
//
1175-
// TODO these are deprecated; use the results of parse instead.
1176-
//
1177-
11781186
// returns true if the document parsed was valid
11791187
[[deprecated("Use the result of parser.parse() instead")]]
11801188
inline bool is_valid() const noexcept;
@@ -1188,11 +1196,9 @@ class parser {
11881196
[[deprecated("Use error_message() on the result of parser.parse() instead, or cout << error")]]
11891197
inline std::string get_error_message() const noexcept;
11901198

1191-
// print the json to std::ostream (should be valid)
1192-
// return false if the tape is likely wrong (e.g., you did not parse a valid
1193-
// JSON).
11941199
[[deprecated("Use cout << on the result of parser.parse() instead")]]
11951200
inline bool print_json(std::ostream &os) const noexcept;
1201+
/** @private Private and deprecated: use `parser.parse(...).doc.dump_raw_tape()` instead */
11961202
inline bool dump_raw_tape(std::ostream &os) const noexcept;
11971203

11981204
//
@@ -1201,54 +1207,54 @@ class parser {
12011207
// TODO find a way to do this without exposing the interface or crippling performance
12021208
//
12031209

1204-
// this should be called when parsing (right before writing the tapes)
1210+
/** @private this should be called when parsing (right before writing the tapes) */
12051211
inline void init_stage2() noexcept;
1206-
really_inline error_code on_error(error_code new_error_code) noexcept;
1207-
really_inline error_code on_success(error_code success_code) noexcept;
1208-
really_inline bool on_start_document(uint32_t depth) noexcept;
1209-
really_inline bool on_start_object(uint32_t depth) noexcept;
1210-
really_inline bool on_start_array(uint32_t depth) noexcept;
1212+
really_inline error_code on_error(error_code new_error_code) noexcept; ///< @private
1213+
really_inline error_code on_success(error_code success_code) noexcept; ///< @private
1214+
really_inline bool on_start_document(uint32_t depth) noexcept; ///< @private
1215+
really_inline bool on_start_object(uint32_t depth) noexcept; ///< @private
1216+
really_inline bool on_start_array(uint32_t depth) noexcept; ///< @private
12111217
// TODO we're not checking this bool
1212-
really_inline bool on_end_document(uint32_t depth) noexcept;
1213-
really_inline bool on_end_object(uint32_t depth) noexcept;
1214-
really_inline bool on_end_array(uint32_t depth) noexcept;
1215-
really_inline bool on_true_atom() noexcept;
1216-
really_inline bool on_false_atom() noexcept;
1217-
really_inline bool on_null_atom() noexcept;
1218-
really_inline uint8_t *on_start_string() noexcept;
1219-
really_inline bool on_end_string(uint8_t *dst) noexcept;
1220-
really_inline bool on_number_s64(int64_t value) noexcept;
1221-
really_inline bool on_number_u64(uint64_t value) noexcept;
1222-
really_inline bool on_number_double(double value) noexcept;
1218+
really_inline bool on_end_document(uint32_t depth) noexcept; ///< @private
1219+
really_inline bool on_end_object(uint32_t depth) noexcept; ///< @private
1220+
really_inline bool on_end_array(uint32_t depth) noexcept; ///< @private
1221+
really_inline bool on_true_atom() noexcept; ///< @private
1222+
really_inline bool on_false_atom() noexcept; ///< @private
1223+
really_inline bool on_null_atom() noexcept; ///< @private
1224+
really_inline uint8_t *on_start_string() noexcept; ///< @private
1225+
really_inline bool on_end_string(uint8_t *dst) noexcept; ///< @private
1226+
really_inline bool on_number_s64(int64_t value) noexcept; ///< @private
1227+
really_inline bool on_number_u64(uint64_t value) noexcept; ///< @private
1228+
really_inline bool on_number_double(double value) noexcept; ///< @private
12231229

12241230
private:
1225-
//
1226-
// The maximum document length this parser supports.
1227-
//
1228-
// Buffers are large enough to handle any document up to this length.
1229-
//
1231+
/**
1232+
* The maximum document length this parser supports.
1233+
*
1234+
* Buffers are large enough to handle any document up to this length.
1235+
*/
12301236
size_t _capacity{0};
12311237

1232-
//
1233-
// The maximum document length this parser will automatically support.
1234-
//
1235-
// The parser will not be automatically allocated above this amount.
1236-
//
1238+
/**
1239+
* The maximum document length this parser will automatically support.
1240+
*
1241+
* The parser will not be automatically allocated above this amount.
1242+
*/
12371243
size_t _max_capacity;
12381244

1239-
//
1240-
// The maximum depth (number of nested objects and arrays) supported by this parser.
1241-
//
1242-
// Defaults to DEFAULT_MAX_DEPTH.
1243-
//
1245+
/**
1246+
* The maximum depth (number of nested objects and arrays) supported by this parser.
1247+
*
1248+
* Defaults to DEFAULT_MAX_DEPTH.
1249+
*/
12441250
size_t _max_depth;
12451251

1246-
//
1247-
// The loaded buffer (reused each time load() is called)
1248-
//
1252+
/**
1253+
* The loaded buffer (reused each time load() is called)
1254+
*/
12491255
std::unique_ptr<char[], decltype(&aligned_free_char)> loaded_bytes;
12501256

1251-
// Capacity of loaded_bytes buffer.
1257+
/** Capacity of loaded_bytes buffer. */
12521258
size_t _loaded_bytes_capacity{0};
12531259

12541260
// all nodes are stored on the doc.tape using a 64-bit word.
@@ -1268,13 +1274,13 @@ class parser {
12681274
inline void write_tape(uint64_t val, internal::tape_type t) noexcept;
12691275
inline void annotate_previous_loc(uint32_t saved_loc, uint64_t val) noexcept;
12701276

1271-
// Ensure we have enough capacity to handle at least desired_capacity bytes,
1272-
// and auto-allocate if not.
1277+
/**
1278+
* Ensure we have enough capacity to handle at least desired_capacity bytes,
1279+
* and auto-allocate if not.
1280+
*/
12731281
inline error_code ensure_capacity(size_t desired_capacity) noexcept;
12741282

1275-
//
1276-
// Read the file into loaded_bytes
1277-
//
1283+
/** Read the file into loaded_bytes */
12781284
inline simdjson_result<size_t> read_file(const std::string &path) noexcept;
12791285

12801286
friend class parser::Iterator;

‎include/simdjson/implementation.h

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,7 @@ class implementation {
136136
const uint32_t _required_instruction_sets;
137137
};
138138

139+
/** @private */
139140
namespace internal {
140141

141142
/**
@@ -186,7 +187,9 @@ class available_implementation_list {
186187
const implementation *detect_best_supported() const noexcept;
187188
};
188189

189-
// Detects best supported implementation on first use, and sets it
190+
/**
191+
* @private Detects best supported implementation on first use, and sets it
192+
*/
190193
class detect_best_supported_implementation_on_first_use final : public implementation {
191194
public:
192195
const std::string& name() const noexcept final { return set_best()->name(); }
@@ -244,6 +247,8 @@ inline const internal::available_implementation_list available_implementations;
244247
* The active implementation.
245248
*
246249
* Automatically initialized on first use to the most advanced implementation supported by this hardware.
250+
*
251+
* @hideinitializer
247252
*/
248253
inline internal::atomic_ptr<const implementation> active_implementation = &internal::detect_best_supported_implementation_on_first_use_singleton;
249254

‎include/simdjson/parsedjson.h

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@
77

88
namespace simdjson {
99

10+
/**
11+
* @deprecated Use `document::parser` instead.
12+
*/
1013
using ParsedJson = dom::parser;
1114

1215
} // namespace simdjson

‎src/isadetection.h

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -57,11 +57,11 @@ POSSIBILITY OF SUCH DAMAGE.
5757
namespace simdjson {
5858

5959
// Can be found on Intel ISA Reference for CPUID
60-
constexpr uint32_t cpuid_avx2_bit = 1 << 5; // Bit 5 of EBX for EAX=0x7
61-
constexpr uint32_t cpuid_bmi1_bit = 1 << 3; // bit 3 of EBX for EAX=0x7
62-
constexpr uint32_t cpuid_bmi2_bit = 1 << 8; // bit 8 of EBX for EAX=0x7
63-
constexpr uint32_t cpuid_sse42_bit = 1 << 20; // bit 20 of ECX for EAX=0x1
64-
constexpr uint32_t cpuid_pclmulqdq_bit = 1 << 1; // bit 1 of ECX for EAX=0x1
60+
constexpr uint32_t cpuid_avx2_bit = 1 << 5; ///< @private Bit 5 of EBX for EAX=0x7
61+
constexpr uint32_t cpuid_bmi1_bit = 1 << 3; ///< @private bit 3 of EBX for EAX=0x7
62+
constexpr uint32_t cpuid_bmi2_bit = 1 << 8; ///< @private bit 8 of EBX for EAX=0x7
63+
constexpr uint32_t cpuid_sse42_bit = 1 << 20; ///< @private bit 20 of ECX for EAX=0x1
64+
constexpr uint32_t cpuid_pclmulqdq_bit = 1 << 1; ///< @private bit 1 of ECX for EAX=0x1
6565

6666
enum instruction_set {
6767
DEFAULT = 0x0,

0 commit comments

Comments
 (0)