api更新

core/include/structive/property/synchronization.hpp

@@ -12,14 +12,19 @@
 #include <utility>
 #include <vector>
 namespace structive {
+/// Defines the default lock-domain topology for properties that actually require managed synchronization.
+/// Stored intrinsic read-only properties are filtered out later and never receive a lock slot, regardless of this default.
 enum class Synchronization_Default {
     independent,
     shared,
     unsynchronized
 };
+/// Changes the default topology used before per-property and group overrides are applied.
 struct Sync_Default_Rule {
     Synchronization_Default value{Synchronization_Default::independent};
 };
+/// Runtime-key override for one property. The key is resolved against the schema when the plan is materialized.
+/// `independent` forces a dedicated domain; `unsynchronized` deliberately removes the property from real locking.
 struct Sync_Property_Rule {
     enum class Mode {
         independent,
@@ -28,15 +33,19 @@ struct Sync_Property_Rule {
     Mode mode{Mode::independent};
     std::string property;
 };
+/// Runtime-key declaration that places multiple properties in one consistency domain.
+/// Group membership affects only properties that require synchronization; intrinsic read-only stored properties remain lock-free.
 struct Sync_Group_Rule {
     std::string name;
     std::vector<std::string> properties;
 };
+/// Compile-time member-pointer form of a single-property synchronization override.
 template <auto Member, Sync_Property_Rule::Mode Mode>
 struct Sync_Member_Rule {
     static constexpr auto member = Member;
     static constexpr auto mode = Mode;
 };
+/// Compile-time member-pointer form of a synchronization group. Member validity is checked against the target schema during materialization.
 template <auto... Members>
 struct Sync_Member_Group_Rule {
     static_assert(sizeof...(Members) > 0);
@@ -71,6 +80,10 @@ Sync_Group_Rule sync_group(std::string_view name, Properties&&... properties) re
     (rule.properties.emplace_back(std::string_view(std::forward<Properties>(properties))), ...);
     return rule;
 }
+/// Runtime-materialized synchronization description.
+/// A plan describes topology, not mutex objects: resolution converts keys and groups into compact lock slots for one schema.
+/// Invalid references, duplicate property configuration, empty groups and duplicate group names are rejected while resolving the plan.
+/// The schema default plan is resolved once per object type; a `Property_Synchronization` override resolves a separate compact layout only for that instance.
 class Synchronization_Plan {
     Synchronization_Default default_mode_{Synchronization_Default::independent};
     std::vector<Sync_Property_Rule> property_rules_;
@@ -143,6 +156,8 @@ concept Synchronization_Spec_Type = requires {
 };
 template <class Type>
 concept Synchronization_Source_Type = Synchronization_Plan_Type<Type> || Synchronization_Spec_Type<Type>;
+/// Builds synchronization configuration without forcing every caller onto runtime strings.
+/// If every rule is already runtime-shaped, this returns `Synchronization_Plan` directly. If any rule carries compile-time member pointers, it returns a typed specification that is later materialized against the concrete schema.
 template <class... Rules>
 auto synchronization(Rules&&... rules) {
     if constexpr ((Runtime_Synchronization_Rule<Rules> && ...)) {
@@ -153,6 +168,9 @@ auto synchronization(Rules&&... rules) {
         return Synchronization_Spec<std::decay_t<Rules>...>{{std::forward<Rules>(rules)...}};
     }
 }
+/// Compact result after applying defaults, overrides, groups and intrinsic property capabilities.
+/// `lock_slots[i]` identifies the mutex domain for property `i`; `unsynchronized_slot` means no mutex exists for that property.
+/// `lock_count` is the number of actual logical mutex domains after read-only filtering and group deduplication.
 template <std::size_t Property_Count>
 struct Resolved_Synchronization_Plan {
     static constexpr std::size_t unsynchronized_slot = std::numeric_limits<std::size_t>::max();