From a1dd0bb6777055bbb775ad070baa219e9f6ae431 Mon Sep 17 00:00:00 2001
From: ToruNiina <niina.toru.68u@gmail.com>
Date: Sun, 2 Feb 2025 14:05:46 +0900
Subject: [PATCH] doc: add accessed()

---
 docs/content.en/docs/features/value.md | 73 ++++++++++++++++++++++++++
 docs/content.ja/docs/features/value.md | 68 ++++++++++++++++++++++++
 2 files changed, 141 insertions(+)

diff --git a/docs/content.en/docs/features/value.md b/docs/content.en/docs/features/value.md
index 3107688..51fb37b 100644
--- a/docs/content.en/docs/features/value.md
+++ b/docs/content.en/docs/features/value.md
@@ -834,3 +834,76 @@ struct bar
     }
 };
 ```
+
+# Checking Whether a Value Has Been Accessed
+
+{{% hint warning %}}
+
+This feature is not enabled by default. To use it, you need to define `TOML11_ENABLE_ACCESS_CHECK`.
+Additionally, since this feature introduces extra processing on parsed values, it may impact runtime performance.
+
+{{% /hint %}}
+
+When compiled with the `TOML11_ENABLE_ACCESS_CHECK` macro defined, the `toml::value` class gains an additional method: `bool accessed() const`.
+This allows you to check whether a value has been accessed after parsing.
+
+```console
+$ g++ -std=c++17 -O2 -DTOML11_ENABLE_ACCESS_CHECK -I/path/to/toml11/include main.cpp
+```
+
+or
+
+```console
+$ cmake -B ./build -DTOML11_ENABLE_ACCESS_CHECK=ON
+```
+
+or
+
+```cmake
+CPMAddPackage(
+    NAME toml11
+    GITHUB_REPOSITORY "ToruNiina/toml11"
+    VERSION 4.4.0
+    OPTIONS "CMAKE_CXX_STANDARD 17" "TOML11_PRECOMPILE ON" "TOML11_ENABLE_ACCESS_CHECK ON"
+    )
+```
+
+This feature allows users to implement code that warns about values defined in a table but never used.
+
+```cpp
+#include <toml.hpp>
+
+namespace yours
+{
+
+Config read_config(const toml::value& input)
+{
+    const auto cfg = read_your_config(input);
+
+    for (const auto& [k, v] : input.as_table())
+    {
+        if (!v.accessed())
+        {
+            std::cerr << toml::format_error("value defined but not used",
+                v.source_location(), "not used");
+        }
+    }
+    return cfg;
+}
+} // namespace yours
+```
+
+This feature is useful when a value is mistakenly defined under the wrong name but is never accessed. For example:
+
+```toml
+# The correct key is "reactions"
+# reactions = [ ":+1:", "star" ]
+
+# This key is incorrect and will not be read
+reaction = [ ":+1:", "star" ]
+```
+
+If this file is read using the above code, `read_your_config` will search for `reactions`. Since it is not defined, it will process `reactions` as an empty array.
+In this case, `input.at("reaction").accessed()` will be `false`, allowing it to be detected as an error.
+
+
diff --git a/docs/content.ja/docs/features/value.md b/docs/content.ja/docs/features/value.md
index 950efcf..771dadd 100644
--- a/docs/content.ja/docs/features/value.md
+++ b/docs/content.ja/docs/features/value.md
@@ -863,3 +863,71 @@ struct bar
     }
 };
 ```
+
+# 値がアクセス済みかどうかチェックする
+
+{{% hint warning %}}
+
+この機能はデフォルトでは有効化されず、使用する際には`TOML11_ENABLE_ACCESS_CHECK`を定義する必要があります。
+また、この機能はパースした値に対して追加の処理を行うため、実行時パフォーマンスが低下する可能性があります。
+
+{{% /hint %}}
+
+`TOML11_ENABLE_ACCESS_CHECK`マクロを定義してコンパイルすると、`toml::value`に`bool accessed() const`メソッドが追加され、パース後にその値にアクセスしたかどうかが確認できるようになります。
+
+```console
+$ g++ -std=c++17 -O2 -DTOML11_ENABLE_ACCESS_CHECK -I/path/to/toml11/include main.cpp
+```
+
+```console
+$ cmake -B ./build -DTOML11_ENABLE_ACCESS_CHECK=ON
+```
+
+```cmake
+CPMAddPackage(
+    NAME toml11
+    GITHUB_REPOSITORY "ToruNiina/toml11"
+    VERSION 4.4.0
+    OPTIONS "CMAKE_CXX_STANDARD 17" "TOML11_PRECOMPILE ON" "TOML11_ENABLE_ACCESS_CHECK ON"
+    )
+```
+
+この機能によって、テーブル内に定義されているものの使用されなかった値についての警告を表示することが可能になります。
+
+```cpp
+#include <toml.hpp>
+
+namespace yours
+{
+
+Config read_config(const toml::value& v)
+{
+    const auto cfg = read_your_config(input);
+
+    for(const auto& [k, v] : input.as_table())
+    {
+        if( ! v.accessed())
+        {
+            std::cerr << toml::format_error("value defined but not used",
+                v.source_location(), "not used");
+        }
+    }
+    return cfg;
+}
+} // yours
+```
+
+この機能は、必要な場合のみ定義されるような値を、名称を間違えて定義してしまった際に役に立つでしょう。
+例えば、
+
+```toml
+# 正しくは reactions 
+# reactions = [ ":+1:", "star" ]
+
+# 名前が違うので読み込めない
+reaction = [ ":+1:", "star" ]
+```
+
+このファイルを上記のコードで読んだ場合、`read_your_config`は`reactions`を探し、定義されていなかったので空の配列として処理するでしょう。
+その場合、`reaction`は`accessed()`が`true`にならないため、エラーとして検出できます。
+