Comment ruleset functions

include/fractal.hpp

@@ -99,20 +99,128 @@ private:
 	etl::vector<mark_rule_t, S_MAX_MARK_RULES> m_mark_rules;
 
 public:
+	/**
+	 * @brief Checks if the maximum number of tokens has been reached
+	 *
+	 * @ret @c true if the number of tokens in the ruleset equals @c S_MAX_TOKENS, @c false otherwise
+	 */
 	bool tokens_full() const;
+
+	/**
+	 * @brief Add new token variable that can be used in this ruleset
+	 *
+	 * @param type   Type of the token to add
+	 * @param value  Value of the token, unused if @p type is @c token_type_e::empty
+	 *
+	 * @ret @c token_id_t of the newly added token, local to this ruleset
+	 * 
+	 * @exception @c mtl::invalid_argument if the given token type is invalid
+	 * @exception @c mtl::length_error if the maximum number of tokens is reached
+	 */
 	token_id_t add_token(token_type_e type, mtl::fixed value = 0);
 
+	/**
+	 * @brief Checks if the maximum number of group characteristics has been reached
+	 *
+	 * @ret @c true if the number of group characteristics in the ruleset equals @c S_MAX_CGROUPS, @c false otherwise
+	 */
 	bool group_characteristics_full() const;
+
+	/**
+	 * @brief Add new group characteristic
+	 *
+	 * @param tokens  @c etl::ivector of @c token_id_t that should be generated inside this group
+	 * @param factor  The number of times the group's tokens are repeatedly generated
+	 *
+	 * @ret @c group_id_t of the newly added group characteristic, local to this ruleset
+	 *
+	 * @exception mtl::invalid_argument if an invalid token was encountered
+	 * @exception mtl::length_error if the maximum number of groups is reached
+	 */
 	group_id_t add_group_characteristic(const etl::ivector<token_id_t>& tokens, uint32_t factor = 1);
 
+	/**
+	 * @brief Checks if the maximum number of weighted groups has been reached
+	 *
+	 * @ret @c true if the number of weighted groups in the ruleset equals @c S_MAX_WGROUPS, @c false otherwise
+	 */
 	bool weighted_groups_full() const;
+
+	/**
+	 * @brief Add new weighted group
+	 *
+	 * Adds weighted group of groups, where each subgroup has a 
+	 * <tt>(weight) / (total weight)</tt> chance of being selected. Weights
+	 * are represented as @c uint32_t.
+	 *
+	 * @param weights  @c etl::ivector of @c etl::pair of @c group_id_t and their corresponding weights
+	 *
+	 * @ret @c weighted_group_id_t of the newly created group
+	 *
+	 * @exception @c mtl::invalid_argument if no groups were supplied, or an invalid group was encountered
+	 * @exception @c mtl::length_error if the maximum number of groups is reached
+	 */
 	weighted_group_id_t add_weighted_group(const etl::ivector<group_id_t>& groups);
 
+	/**
+	 * @brief Checks if the maximum number of branch rules has been reached
+	 *
+	 * @ret @c true if the number of branch rules in the ruleset equals @c S_MAX_BRANCH_RULES, @c false otherwise
+	 */
 	bool branch_rules_full() const;
+
+	/**
+	 * @brief Add a new unweighted branch rule to the ruleset
+	 *
+	 * Branch rules describe what groups can be generated given a token.
+	 * Branch rules can use either plain groups or weighted groups as their output.
+	 *
+	 * @param match  Token to match and generate the group in place of
+	 * @param group  Group to generate
+	 *
+	 * @ret @c branch_rule_id_t of the newly added branch rule
+	 *
+	 * @exception @c mtl::invalid_argument if an invalid token or group was supplied
+	 * @exception @c mtl::length_error if the maximum number of branch rules was reached
+	 */
 	branch_rule_id_t add_branch_rule(token_id_t match, group_id_t group);
+
+	/**
+	 * @brief Add a new weighted branch rule to the ruleset
+	 *
+	 * Branch rules describe what groups can be generated given a token.
+	 * Branch rules can use either plain groups or weighted groups as their output.
+	 *
+	 * @param match   Token to match and generate the group in place of
+	 * @param wgroup  Weighted group to select from, only one subgroup is generated
+	 *
+	 * @ret @c branch_rule_id_t of the newly added branch rule
+	 *
+	 * @exception @c mtl::invalid_argument if an invalid token or group was supplied
+	 * @exception @c mtl::length_error if the maximum number of branch rules was reached
+	 */
 	branch_rule_id_t add_branch_rule_weighted(token_id_t match, weighted_group_id_t wgroup);
 
+	/**
+	 * @brief Checks if the maximum number of mark rules has been reached
+	 *
+	 * @ret @c true if the number of mark rules in the ruleset equals @c S_MAX_MARK_RULES, @c false otherwise
+	 */
 	bool mark_rules_full() const;
+
+	/** @brief Add a new marking rule to the ruleset
+	 *
+	 * Mark rules describe what tokens should have their positions output
+	 * each generation. If a token has a match, its position and a tag is output.
+	 *
+	 * @param match  Token to match and mark
+	 * @param tag    Marking identifier, does not need to be unique
+	 *
+	 * @ret @c mark_rule_id_t of the newly added mark rule
+	 *
+	 * @exception @c mtl::invalid_argument if an invalid token was supplied
+	 * @exception @c mtl::length_error if the maximum number of mark rules was reached
+	 */
 	mark_rule_id_t add_mark_rule(token_id_t match, uint32_t tag);
 };