add comments in variable_info

src/variable_info.cpp

@@ -165,19 +165,13 @@ namespace
 		}
 	}
 
+	/// Adds a .<key> to teh current cariable
 	template<const variable_info_3_type vit>
 	class get_variable_key_visitor
 		: public variable_info_visitor<vit, void>
 	{
 	public:
 		get_variable_key_visitor(const std::string& key) : key_(key) {}
-
-		void from_config(typename maybe_const<vit, config>::type & cfg, typename get_variable_key_visitor::param_type state) const
-		{
-			state.type_ = state_named;
-			state.key_ = key_;
-			state.child_ = &cfg;
-		}
 		void from_named(typename get_variable_key_visitor::param_type state) const 
 		{			
 			if(key_ == "length")
@@ -188,21 +182,29 @@ namespace
 			}
 			else
 			{
-				return from_config(get_child_at<vit>(*state.child_, state.key_, 0), state);
+				return do_from_config(get_child_at<vit>(*state.child_, state.key_, 0), state);
 			}
 		}
 		void from_start(typename get_variable_key_visitor::param_type state) const 
 		{
-			return from_config(*state.child_, state);
+			return do_from_config(*state.child_, state);
 		}
 		void from_indexed(typename get_variable_key_visitor::param_type state) const 
 		{
-			return from_config(get_child_at<vit>(*state.child_, state.key_, state.index_), state);
+			return do_from_config(get_child_at<vit>(*state.child_, state.key_, state.index_), state);
 		}
 	private:
+		void do_from_config(typename maybe_const<vit, config>::type & cfg, typename get_variable_key_visitor::param_type state) const
+		{
+			state.type_ = state_named;
+			state.key_ = key_;
+			state.child_ = &cfg;
+		}
 		const std::string& key_;
 	};
 
+	/// appens a [index] to the state.
+	/// we only support from_named since [index][index2] or a.length[index] both doesn't make sense.
 	template<const variable_info_3_type vit>
 	class get_variable_index_visitor
 		: public variable_info_visitor<vit, void>
@@ -233,6 +235,7 @@ namespace
 			check_valid_name(state.key_);
 			return (*state.child_)[state.key_];
 		}
+		///Defined below for different cases.
 		typename as_skalar_visitor::result_type from_temporary(typename as_skalar_visitor::param_type state) const;
 	};
 	/// this type of value like '.length' are readonly values so we only support them for reading.
@@ -253,7 +256,8 @@ namespace
 		throw invalid_variablename_exception();
 	}
 
-	///tries to convert to a (const) config&, unlike range based operation this also supports 'variable_child'
+	/// tries to convert to a (const) config&, unlike range based operation this also supports 'from_start'
+	/// Note: Currently getting the 'from_start' case here is impossible, becasue we always apply at least one string key.
 	template<const variable_info_3_type vit>
 	class as_container_visitor
 		: public variable_info_visitor_const<vit, typename maybe_const<vit, config>::type&>

src/variable_info.hpp

@@ -35,6 +35,7 @@ class variable_info_3
 public:
 
 	typedef typename variable_info_3_detail::maybe_const<vit,config>::type t_config;
+	/// Doesn't throw
 	variable_info_3(const std::string& varname, t_config& vars);
 	~variable_info_3();
 	std::string get_error_message() const;
@@ -64,25 +65,33 @@ class variable_info_3
 	void calculate_value();
 };
 
-/// Gives special variable changign meethods that cannot be done with vit == vit_const
+/// Extends variable_info_3 with methods that can only be applied if vit != vit_const
 template<const variable_info_3_detail::variable_info_3_type vit>
 class non_const_variable_info_3 : public variable_info_3<vit>, variable_info_3_detail::enable_if_non_const<vit>::type
 {
 public:
 	non_const_variable_info_3(const std::string& name, config& game_vars) : variable_info_3<vit>(name, game_vars) {};
 	~non_const_variable_info_3() {}
+
 	/// clears the vale this object points to
 	/// if only_tables = true it will not clear attribute values.
+	/// might throw invalid_variablename_exception
 	void clear(bool only_tables = false) const;
-	/// the following 4 functions are used by [set_variables]
-	///     they destroy the passed vector. (make it empty).
-	/// return: the new appended range
+
+	// the following 4 functions are used by [set_variables]
+	// they destroy the passed vector. (make it empty).
+
+	/// @return: the new appended range
+	/// might throw invalid_variablename_exception
 	config::child_itors append_array(std::vector<config> childs) const;
-	/// return: the new inserted range
+	/// @return: the new inserted range
+	/// might throw invalid_variablename_exception
 	config::child_itors insert_array(std::vector<config> childs) const;
-	/// return: the new range
+	/// @return: the new range
+	/// might throw invalid_variablename_exception
 	config::child_itors replace_array(std::vector<config> childs) const;
 	/// merges
+	/// might throw invalid_variablename_exception
 	void merge_array(std::vector<config> childs) const;
 };
 
@@ -93,7 +102,7 @@ class non_const_variable_info_3 : public variable_info_3<vit>, variable_info_3_d
 typedef non_const_variable_info_3<variable_info_3_detail::vit_create_if_not_existent> variable_access_create;
 /**
 	this variable accessor will throw an exception when trying to access a non existent table.
-	Note that the other types can throw too if name is invlid.
+	Note that the other types can throw too if name is invlid like '..[[[a'.
 */
 typedef non_const_variable_info_3<variable_info_3_detail::vit_throw_if_not_existent>  variable_access_throw;
 /**

src/variable_info_detail.hpp

@@ -24,11 +24,12 @@ namespace variable_info_3_detail
 	enum variable_info_3_type {vit_const, vit_create_if_not_existent, vit_throw_if_not_existent,  };
 	enum variable_info_3_state_type { 
 		state_start = 0, // for internal use
+		                 // only used at the 'starting_pos' of the variable_info_3::calculate_value algorithm 
 		state_named,     // the result of .someval this can eigher man an attribute value or an 
 		                 // child range
 		state_indexed,   // the result of .someval[index] this is never an attribute value, 
 		                 // this is always a single config.
-		state_temporary, // the result of .length this value can never be written, it can onyl be read.
+		state_temporary, // the result of .length this value can never be written, it can only be read.
 
 	};
 
@@ -78,13 +79,17 @@ namespace variable_info_3_detail
 			child_ = &vars;
 		}
 
-
+		// The meaning of the following 3 depends on 'type_', but usualy the case is:
+		// the current config is  child_->child_at(key_, index_).
 		t_child* child_;
 		std::string key_;
 		int index_;
 
+		// If we have a temporary value like .length
+		// Then we store the result here.
 		config::attribute_value temp_val_;
 
+		// See the definition of 'variable_info_3_state_type'
 		variable_info_3_state_type type_;
 	};
 }