Skip to content

Commit 240f02f

Browse files
orefkovorefkov
committed
Дополнена документация
1 parent 934e871 commit 240f02f

1 file changed

Lines changed: 104 additions & 37 deletions

File tree

‎include/simjson/json.h‎

Lines changed: 104 additions & 37 deletions
Original file line numberDiff line numberDiff line change
@@ -414,8 +414,13 @@ class JsonValueTempl : public Json {
414414
swap(t);
415415
return *this;
416416
}
417-
418-
/// Обращение к свойству константного объекта по ключу. Не создаёт новую пару при отсутствии ключа
417+
/*!
418+
* @brief Обращение к свойству константного объекта по ключу.
419+
* @tparam T - типа ключа
420+
* @param key - ключ
421+
* @return const json_value& - ссылка на значение ключа.
422+
* Если значение не объект, или ключа нет, не создаёт новую пару, а возвращает ссылку на UNDEFINED.
423+
*/
419424
template<jt::JsonKeyType<K> T>
420425
const json_value& at(T&& key) const {
421426
if (type_ == Object) {
@@ -424,14 +429,28 @@ class JsonValueTempl : public Json {
424429
}
425430
return UNDEFINED;
426431
}
427-
428-
/// Обращение к свойству константного объекта по ключу. Не создаёт новую пару при отсутствии ключа
432+
/*!
433+
* @brief Обращение к свойству константного объекта по ключу.
434+
* @tparam T - типа ключа
435+
* @param key - ключ
436+
* @return const json_value& - ссылка на значение ключа.
437+
* Если значение не объект, или ключа нет, не создаёт новую пару, а возвращает ссылку на UNDEFINED.
438+
*/
429439
template<jt::JsonKeyType<K> T>
430440
const json_value& operator[](T&& key) const {
431441
return at(std::forward<T>(key));
432442
}
433-
434-
/// Обращение к свойству константного объекта по ключам. Не создаёт новую пару при отсутствии ключа
443+
/*!
444+
* @brief Обращение к свойству константного объекта по набору ключей.
445+
* @details Функция последовательно переходит от значения к значению по заданным ключам.
446+
* Как только указанный ключ не будет найден, перебор останавливается.
447+
* Например: config("a", "b", "c") для объекта {"a": {"b": {"c": 10}}} вернёт ссылку на 10.
448+
* @tparam T - типа ключа
449+
* @param key - ключ
450+
* @param ...args - остальные ключи
451+
* @return const json_value& - ссылка на значение ключа.
452+
* Если значение не объект, или указанного ключа нет, не создаёт новую пару, а возвращает ссылку на UNDEFINED.
453+
*/
435454
template<jt::JsonKeyType<K> T, typename...Args>
436455
const json_value& operator()(T&& key, Args&&...args) const {
437456
const json_value& res = at(std::forward<T>(key));
@@ -441,9 +460,14 @@ class JsonValueTempl : public Json {
441460
return res.is_undefined() ? res : res(std::forward<Args>(args)...);
442461
}
443462
}
444-
445-
/// Обращение к свойству объекта по ключу. Создаёт новую пару при отсутствии ключа
446-
/// Если значение не объект, заменят его на объект
463+
/*!
464+
* @brief Обращение к свойству объекта по ключу.
465+
* @tparam T - тип ключа
466+
* @param key - ключ
467+
* @return json_value& - ссылку на значение ключа.
468+
* @details Если значение не json-объект, то "превращает" его в json-объект.
469+
* Если указанного ключа нет - добавляет в json-объект этот ключ с пустым значением.
470+
*/
447471
template<jt::JsonKeyType<K> T>
448472
json_value& operator[](T&& key) {
449473
if (type_ != Object) {
@@ -452,9 +476,17 @@ class JsonValueTempl : public Json {
452476
}
453477
return as_object()->try_emplace(std::forward<T>(key)).first->second;
454478
}
455-
456-
/// Установка значения свойству объекта по ключу. Создаёт новую пару при отсутствии ключа
457-
/// Если значение не объект, заменят его на объект
479+
/*!
480+
* @brief Установка значения свойству json-объекта по ключу.
481+
* @tparam Key - тип ключа
482+
* @tparam Args - типы аргументов для создания json-значения по указанному ключу
483+
* @param key - ключ
484+
* @param args - аргументы для создания json-значения по указанному ключу
485+
* @return json_value& - ссылку на json-значение по указанному ключу
486+
* @details Если значение не json-объект, то "превращает" его в json-объект.
487+
* Если указанного ключа нет - добавляет в json-объект этот ключ с заданными аргументами,
488+
* иначе присваивает ему аргументы.
489+
*/
458490
template<jt::JsonKeyType<K> Key, typename ... Args>
459491
json_value& set(Key&& key, Args&& ... args) {
460492
if (type_ != Object) {
@@ -463,8 +495,7 @@ class JsonValueTempl : public Json {
463495
}
464496
return as_object()->emplace(std::forward<Key>(key), std::forward<Args>(args)...).first->second;
465497
}
466-
467-
/// Обращение к элементу константного массива по индексу.
498+
/// Обращение к элементу константного массива по индексу. Если это не json-массив или индекс за границами массива - возвращает ссылку на UNDEFINED.
468499
const json_value& at(size_t idx) const {
469500
if (type_ == Array) {
470501
const auto& arr = *as_array();
@@ -474,15 +505,19 @@ class JsonValueTempl : public Json {
474505
}
475506
return UNDEFINED;
476507
}
477-
/// Обращение к элементу константного массива по индексу.
508+
/// Обращение к элементу константного массива по индексу. Если это не json-массив или индекс за границами массива - возвращает ссылку на UNDEFINED.
478509
const json_value& operator[](size_t idx) const {
479510
return at(idx);
480511
}
481-
482-
/// Обращение к элементу массива по индексу.
483-
/// Если значение не массив - заменяется на массив.
484-
/// Если индекс больше длины массива - увеличивает массив до заданного индекса
485-
/// Если индекс == -1 - добавляет в массив ещё один элемент
512+
/*!
513+
* @brief Обращение к элементу массива по индексу.
514+
*
515+
* @param idx - индекс элемента
516+
* @return json_value& - ссылку на указанный элемент массива.
517+
* @details Если это значение не json-массив - "превращает" его в массив.
518+
* Если индекс == -1 - добавляет в массив ещё один элемент.
519+
* Если индекс больше длины массива - увеличивает массив до заданного индекса.
520+
*/
486521
json_value& operator[](size_t idx) {
487522
if (type_ != Array) {
488523
assert(this != &UNDEFINED);
@@ -497,7 +532,7 @@ class JsonValueTempl : public Json {
497532
}
498533
return arr[idx];
499534
}
500-
/// Количество элементов массива или ключей объекта
535+
/// Количество элементов json-массива или ключей json-объекта
501536
size_t size() const {
502537
if (type_ == Array) {
503538
return as_array()->size();
@@ -506,24 +541,51 @@ class JsonValueTempl : public Json {
506541
}
507542
return 0;
508543
}
509-
510-
/// Слияние с другим JSON. Если replace == true, то другой JSON имеет приоритет, если он не undefined.
511-
/// Если оба объекта массивы, то при append_arrays = true другой массив дописывается к этому массиву.
512-
/// Если оба JSONа объекты - то сливаются по ключам.
513-
/// Иначе другой JSON заменяет текущее значение.
544+
/*!
545+
* @brief Слияние с другим JSON.
546+
* @param other - другое json-значение
547+
* @param replace - заменять другим при слиянии.
548+
* @param append_arrays - при слиянии json-массивов объединять их.
549+
* @details Если replace == true, то другой JSON имеет приоритет и для простых типов, если он не undefined, он заменит текущий.
550+
* Если оба объекта json-массивы, то при append_arrays = true другой массив дописывается к этому массиву,
551+
* иначе если replace == true, то заменит текущий массив.
552+
* Если оба JSONа объекты - то сливаются по ключам. Ключи из другого объекта, которых нет в текущем - добавятся в текущий
553+
* объект. Которые есть - при replace == true будут заменены.
554+
*/
514555
void merge(const json_value& other, bool replace = true, bool append_arrays = false);
515-
516-
/// Распарсить текст с json.
556+
/*!
557+
* @brief Распарсить текст с json.
558+
*
559+
* @param jsonString - строка текста, которую надо распарсить.
560+
* @return std::tuple<json_value, JsonParseResult, unsigned, unsigned> - tuple, содержащую:
561+
* json_value - получившееся значение, если парсинг успешный, или UNDEFINED, в случае ошибок;
562+
* JsonParseResult - код ошибки парсинга, Success в случае успеха;
563+
* unsigned line, unsigned col - в случае ошибки это номера строки/колонки возникновения ошибки.
564+
*/
517565
static std::tuple<json_value, JsonParseResult, unsigned, unsigned> parse(ssType jsonString);
518-
519-
/// Сериализовать значение в lstring<K, 0>. При prettify == true - добавляет переносы строк
520-
/// и отступы в указанное количество указанных символов, по умолчанию - два пробела.
521-
/// При order_keys == true - сортирует ключи объектов по их имени
566+
/*!
567+
* @brief Сериализовать json-значение в строку
568+
* @param stream - строка, в которую сохранять
569+
* @param prettify - "украшать", в случае true в строке будут добавляться переносы строк и отступы.
570+
* @param order_keys - упорядочить ключи json-объектов. По стандарту порядок ключей в JSON не задаётся и не влияет
571+
* на валидность, однако часто требуется для повторяемости результатов придерживаться одного и того же
572+
* порядка вывода при разных запусках. В этом случае вывод ключей будет осуществляться упорядоченно
573+
* "побайтовым сравнением".
574+
* @param indent_symbol - при "украшении" задаёт символ для отступов, по умолчанию пробел.
575+
* @param indent_count - количество символов отступа на один уровень, по умолчанию 2.
576+
*/
522577
void store(lstring<K, 0, true>& stream, bool prettify = false, bool order_keys = false, K indent_symbol = ' ', unsigned indent_count = 2) const;
523-
524-
/// Сериализовать значение в lstring<K, 0>. При prettify == true - добавляет переносы строк
525-
/// и отступы в указанное количество указанных символов, по умолчанию - два пробела.
526-
/// При order_keys == true - сортирует ключи объектов по их имени
578+
/*!
579+
* @brief Сериализовать json-значение в строку
580+
* @param prettify - "украшать", в случае true в строке будут добавляться переносы строк и отступы.
581+
* @param order_keys - упорядочить ключи json-объектов. По стандарту порядок ключей в JSON не задаётся и не влияет
582+
* на валидность, однако часто требуется для повторяемости результатов придерживаться одного и того же
583+
* порядка вывода при разных запусках. В этом случае вывод ключей будет осуществляться упорядоченно
584+
* "побайтовым сравнением".
585+
* @param indent_symbol - при "украшении" задаёт символ для отступов, по умолчанию пробел.
586+
* @param indent_count - количество символов отступа на один уровень, по умолчанию 2.
587+
* @return строку с JSON.
588+
*/
527589
lstring<K, 0, true> store(bool prettify = false, bool order_keys = false, K indent_symbol = ' ', unsigned indent_count = 2) const {
528590
lstring<K, 0, true> res;
529591
store(res, prettify, order_keys, indent_symbol, indent_count);
@@ -616,14 +678,19 @@ std::tuple<JsonValueTempl<K>, JsonParseResult, unsigned, unsigned> JsonValueTemp
616678
return {std::move(parser.result_), res, parser.line_, parser.col_};
617679
}
618680

681+
/// Алиас для JsonValue с символами u8s
619682
using JsonValue = JsonValueTempl<u8s>;
683+
/// Алиас для JsonValue с символами uws
620684
using JsonValueW = JsonValueTempl<uws>;
685+
/// Алиас для JsonValue с символами u16s
621686
using JsonValueU = JsonValueTempl<u16s>;
687+
/// Алиас для JsonValue с символами u32s
622688
using JsonValueUU = JsonValueTempl<u32s>;
623689

624-
// Один объект "пустышка"
690+
/// Один объект "пустышка"
625691
template<typename K>
626692
inline const JsonValueTempl<K> JsonValueTempl<K>::UNDEFINED;
693+
627694
/*!
628695
* @brief Прочитать файл в строку
629696
* @param filePath

0 commit comments

Comments
 (0)