diff --git a/inflection/src/inflection/dialog/InflectableStringConcept.hpp b/inflection/src/inflection/dialog/InflectableStringConcept.hpp index 809f57ea..617b7f63 100644 --- a/inflection/src/inflection/dialog/InflectableStringConcept.hpp +++ b/inflection/src/inflection/dialog/InflectableStringConcept.hpp @@ -40,6 +40,9 @@ class INFLECTION_CLASS_API inflection::dialog::InflectableStringConcept * @return true when the value is empty. */ bool isExists() const override; + /** + * Return a string helpful for debugging purposes. + */ ::std::u16string toString() const override; private: diff --git a/inflection/src/inflection/dialog/SemanticConceptList.hpp b/inflection/src/inflection/dialog/SemanticConceptList.hpp index d6111726..757d8401 100644 --- a/inflection/src/inflection/dialog/SemanticConceptList.hpp +++ b/inflection/src/inflection/dialog/SemanticConceptList.hpp @@ -33,8 +33,17 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticConceptList bool avoidAffixRedundancy { true }; public: + /** + * Put constraint feature and value into the SemanticConceptList. + * @param feature the feature of the constraint to be added. + * @param featureValue the value of the constraint. + */ void putConstraint(const SemanticFeature& feature, ::std::u16string_view featureValue) override; - void clearConstraint(const SemanticFeature& feature) override; + /** + * Clean the constraint feature in the SemanticConceptList. + * @param feature the feature of the constraint to be clearn. + */ + void clearConstraint(const SemanticFeature& feature) override; void reset() override; public: /* protected */ diff --git a/inflection/src/inflection/dialog/SemanticFeature.hpp b/inflection/src/inflection/dialog/SemanticFeature.hpp index ead87c6f..1b671c1a 100644 --- a/inflection/src/inflection/dialog/SemanticFeature.hpp +++ b/inflection/src/inflection/dialog/SemanticFeature.hpp @@ -20,6 +20,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeature /// @endcond public: + /** + * Metadata about how a SemanticFeature is bounded. + */ enum Type { NoValue, BoundedValue, @@ -60,13 +63,31 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeature */ virtual const ::std::u16string& getName() const; /** - * Returns the possible values of this SemanticFeature. Only bounded SemanticFeatures can have a non-empty set of bounded values. + * Returns the possible values of this SemanticFeature. Only bounded SemanticFeatures + * can have a non-empty set of bounded values. */ virtual const ::std::set<::std::u16string>& getBoundedValues() const; + /** + * True if this semantic feature can be referenced by the bounded values directly or + * aliased without specifying the name. + */ virtual bool isAliased() const; bool operator<(const SemanticFeature& other) const; + /** + * Returns true when both objects refer to the same semantic feature, with the same + * name. + * @param other The semantic feature object to be compared with this. + * @return True if the two semantic feature are the same, false otherwise. + */ bool operator==(const SemanticFeature& other) const; + /** + * Construct the SemanticFeature from the name, type, bounded values. + * @param name The name of the SemanticFeature. + * @param type The type of the SemanticFeature. + * @param boundedValues The set of values bounded to the feature. + * @param aliased To indicate the feature is an alias. + */ SemanticFeature(const ::std::u16string& name, Type type, const ::std::set<::std::u16string>& boundedValues, bool aliased); /** * The copy constructor diff --git a/inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp b/inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp index b2a1392b..4f546e65 100644 --- a/inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp +++ b/inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp @@ -27,6 +27,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase private: /* package */ const SemanticFeatureModel* model { }; protected: /* package */ + /** + * All the constraints + */ ::std::map constraints { }; public: /* protected */ @@ -34,11 +37,39 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase * Returns the SemanticFeatureModel used to create this string. */ virtual const SemanticFeatureModel* getModel() const; + /** + * Get the value of the semantic feature. + * @param feature The semantic feature object. + * @return The value of the constraint feature. + */ virtual const ::std::u16string* getConstraint(const SemanticFeature& feature) const; + /** + * Check if the semantic feature has been added as a constraint. + * @param feature The semantic feature object. + * @return True if the semantic feature is in this, false otherwise. + */ virtual bool hasConstraint(const SemanticFeature& feature) const; + /** + * Add a semantic feature with a value as a constraint. + * @param feature The semantic feature object of the constraint to be added. + * @param featureValue The value of the feature. + */ virtual void putConstraint(const SemanticFeature& feature, ::std::u16string_view featureValue); + /** + * Add a semantic feature with a value as a constraint by the name of the SemanticFeature. + * @param featureName The name of the feature. + * @param featureValue The value of the feature. + */ virtual void putConstraintByName(::std::u16string_view featureName, ::std::u16string_view featureValue); + /** + * Clear the specified semantic constraint feature. + * @param feature The semantic feature of the constraint to be cleared. + */ virtual void clearConstraint(const SemanticFeature& feature); + /** + * Clear the specified semantic constraint feature by the given feature name. + * @param featureName The name of the constraint to be cleared. + */ virtual void clearConstraintByName(::std::u16string_view featureName); /** * Returns {@code true} if a value exists for the given constraints @@ -53,11 +84,15 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase */ virtual SpeakableString* getFeatureValue(const SemanticFeature& feature) const = 0; /** - * Returns the String value of the specified feature for this concept, given its current constraints. + * Returns the String value of the specified feature for this concept, given its + * current constraints. * The featureName will be automatically converted to a SemanticFeature for lookup. */ virtual SpeakableString* getFeatureValueByName(::std::u16string_view featureName) const; protected: /* protected */ + /** + * The semantic feature for the spoken form of a string. + */ virtual const SemanticFeature* getSpeakFeature() const; public: @@ -68,8 +103,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase /** * This constructor for the abstract class should be called by the subclasses. - * @param model The SemanticFeatureModel that provides all of the features, valid constraints, default functions - * and other relevant information for a given language. + * @param model The SemanticFeatureModel that provides all of the features, + * valid constraints, default functions + * and other relevant information for a given language. */ explicit SemanticFeatureConceptBase(const SemanticFeatureModel* model); /** diff --git a/inflection/src/inflection/dialog/SemanticFeatureModel.hpp b/inflection/src/inflection/dialog/SemanticFeatureModel.hpp index 7fcc1038..ab8fb154 100644 --- a/inflection/src/inflection/dialog/SemanticFeatureModel.hpp +++ b/inflection/src/inflection/dialog/SemanticFeatureModel.hpp @@ -37,6 +37,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final std::unique_ptr defaultDisplayFunction; public: + /** + * The name of the speak semantic feature. + */ static constexpr auto SPEAK = u"speak"; /** @@ -47,28 +50,56 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final * Returns the SemanticFeatureModel_DisplayData associated with the semantic value in this SemanticFeatureModel */ const SemanticFeatureModel_DisplayData* getDisplayData(const SemanticValue& semantic) const; + /** + * Return the semantic feature by the name. + * @param name The name of the semantic feature. + */ const SemanticFeature* getFeature(::std::u16string_view name) const; + /** + * If a feature name is aliasable, return the associated semantic feature and its value. + * If a semantic feature can be more than one name, the value will have the canonical name. + * This can happen if the semantic feature has been deprecated, or has more than one known + * name for the value. + * @param name The name of the semantic feature. + * @return The semantic feature will be null if no alias was found. + */ ::std::pair<::inflection::dialog::SemanticFeature*, ::std::u16string> getFeatureAlias(::std::u16string_view name) const; /** * Returns the locale created with this SemanticFeatureModel. */ const util::ULocale& getLocale() const; + /** + * Returns the registered feature function for the requested semantic feature. + * @param feature The feature to request. + * @return Returns null if no feature function exists. + */ const DefaultFeatureFunction* getDefaultFeatureFunction(const SemanticFeature& feature) const; + /** + * Register a default feature function for a semantic feature. + * @param feature The feature to register the function for. + * @param function The feature function to call for the semantic feature. This + * SemanticFeatureModel will adopt ownership of this function, and it will be + * deleted when this SemanticFeatureModel is deleted. + */ void putDefaultFeatureFunction(const SemanticFeature& feature, DefaultFeatureFunction* function); /** - * This function works the same way as putDefaultFeatureFunction, but an exception is thrown if the feature is unknown. + * This function works the same way as putDefaultFeatureFunction, but an exception is + * thrown if the feature is unknown. * @param feature The name of the SemanticFeature in this SemanticFeatureModel. - * @param function The function to derive the specified SemanticFeature for the locale when it's not specified by available SemanticFeatureModel_DisplayData. + * @param function The function to derive the specified SemanticFeature for the locale when + * it's not specified by available SemanticFeatureModel_DisplayData. */ void putDefaultFeatureFunctionByName(::std::u16string_view feature, DefaultFeatureFunction* function); /** - * Returns the function is used for inflecting phrases when no constraints match the available SemanticFeatureModel_DisplayData. + * Returns the function is used for inflecting phrases when no constraints match the available + * SemanticFeatureModel_DisplayData. * When it's null, then there is no way to inflect phrases from the constraints. * @see getDisplayData */ const DefaultDisplayFunction* getDefaultDisplayFunction() const; /** - * This function is used for inflecting phrases when no constraints match the available SemanticFeatureModel_DisplayData. + * This function is used for inflecting phrases when no constraints match the available + * SemanticFeatureModel_DisplayData. * Normally this does not need to be set. * @see getDisplayData */ @@ -82,6 +113,12 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final * Creates a default SemanticFeatureModel for a given locale without any display data. */ explicit SemanticFeatureModel(const ::inflection::util::ULocale& locale); + /** + * Creates a SemanticFeatureModel for a given locale with a mapping of display data used for + * constructing things like a SemanticConcept. + * @param locale The locale. + * @param semanticValueMap The mapping of a semantic value to display data. + */ SemanticFeatureModel(const ::inflection::util::ULocale& locale, const ::std::map& semanticValueMap); /** * Destructor diff --git a/inflection/src/inflection/dialog/SemanticValue.hpp b/inflection/src/inflection/dialog/SemanticValue.hpp index 87ec6f9d..cad3b043 100644 --- a/inflection/src/inflection/dialog/SemanticValue.hpp +++ b/inflection/src/inflection/dialog/SemanticValue.hpp @@ -47,6 +47,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticValue */ std::strong_ordering operator<=>(const SemanticValue&) const; + /** + * Construct a SemanticValue by a label and a string value. + */ SemanticValue(const ::std::u16string& label, const ::std::u16string& string); /** * Destructor diff --git a/inflection/src/inflection/dialog/SpeakableString.hpp b/inflection/src/inflection/dialog/SpeakableString.hpp index 5fd7a8f6..c09e99a4 100644 --- a/inflection/src/inflection/dialog/SpeakableString.hpp +++ b/inflection/src/inflection/dialog/SpeakableString.hpp @@ -44,11 +44,39 @@ class INFLECTION_CLASS_API inflection::dialog::SpeakableString */ virtual bool speakEqualsPrint() const; + /** + * Return a string helpful for debugging purposes. + */ ::std::u16string toString() const override; + /** + * Returns true when both objects refer to the speakable string, with the same print and speak string. + * @param o The speakable string object to be compared with this. + * @return True if the two speakable string are the same, false otherwise. + */ bool operator==(const ::inflection::dialog::SpeakableString& o) const; + /** + * Equivalent to the inverse of operator==. + * @param o The speakable string object to be compared with this. + * @return True if the two display value are not the same, false otherwise. + */ bool operator!=(const ::inflection::dialog::SpeakableString& o) const; + /** + * Create a new speakable string by appened other to this. + * @param o the speakable string to be appened with this. + * @return the result speakable string object. + */ SpeakableString operator+(const ::inflection::dialog::SpeakableString& o) const; + /** + * Assigns a speakable string to this. + * @param o the speakable string to be assigned to this. + * @return the result speakable string object. + */ SpeakableString& operator=(const ::inflection::dialog::SpeakableString& o); + /** + * Appends a speakable string to this. + * @param o the speakable string to be appended to this. + * @return the result speakable string object. + */ SpeakableString& operator+=(const ::inflection::dialog::SpeakableString& o); /** diff --git a/inflection/src/inflection/exception/XMLParseException.hpp b/inflection/src/inflection/exception/XMLParseException.hpp index 174bf059..4eca8e5d 100644 --- a/inflection/src/inflection/exception/XMLParseException.hpp +++ b/inflection/src/inflection/exception/XMLParseException.hpp @@ -22,6 +22,10 @@ class INFLECTION_CLASS_API inflection::exception::XMLParseException public: XMLParseException(); + /** + * Construct an XMLParseException with a message. + * @param message The debugging message of this XML parse exception. + */ explicit XMLParseException(const std::u16string& message); ~XMLParseException() override; }; diff --git a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp index 5c5fbc25..03cd645f 100644 --- a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp +++ b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp @@ -39,6 +39,13 @@ class INFLECTION_CLASS_API inflection::lang::features::LanguageGrammarFeatures_F virtual std::map getConstraints() const; public: /* package */ + /** + * Construct a feature by value and a mapping of constraints. + * @param value the name of the feature. + * @param constraints The constraints that are valid for the value. This map contains + * grammatical category name mapped to the specific value valid for the + * grammatical category. + */ LanguageGrammarFeatures_Feature(const std::u16string& value, const std::map& constraints); /** * Destructor diff --git a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarCategory.hpp b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarCategory.hpp index e89c3745..84d25d8b 100644 --- a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarCategory.hpp +++ b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarCategory.hpp @@ -59,7 +59,15 @@ class INFLECTION_CLASS_API inflection::lang::features::LanguageGrammarFeatures_G * @param grammemeValue Use getValues() to get the list of values that can be used as an argument. */ std::multimap getGrammemeDependenciesForValue(std::u16string_view grammemeValue) const; - virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarCategory& o) const; + + /** + * Compares the name of this grammar category with the other.. + * @param other The grammar category object to be compared with this. + * @return the value 0 if the name of the argument other is equal to the name of this; a value -1 if the name + * of this is lexicographically less than the name of the argument other; and a value 1 if the name + * of this is lexicographically greater than the name of the argument other. + */ + virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarCategory& other) const; bool operator<(const LanguageGrammarFeatures_GrammarCategory& other) const; diff --git a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarFeatures.hpp b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarFeatures.hpp index 04aed864..41a3c876 100644 --- a/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarFeatures.hpp +++ b/inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarFeatures.hpp @@ -37,10 +37,22 @@ class INFLECTION_CLASS_API inflection::lang::features::LanguageGrammarFeatures_G * If this feature is bounded, these are the valid values. */ std::vector<::inflection::lang::features::LanguageGrammarFeatures_Feature> getValues() const; - virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarFeatures& o) const; + /** + * Compares the name of this grammar features with the other.. + * @param other The grammar features object to be compared with this. + * @return the value 0 if the name of the argument other is equal to the name of this; a value -1 if the name + * of this is lexicographically less than the name of the argument other; and a value 1 if the name + * of this is lexicographically greater than the name of the argument other. + */ + virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarFeatures& other) const; bool operator<(const LanguageGrammarFeatures_GrammarFeatures& other) const; protected: /* package */ + /** + * Construct a grammar features with name, and values. + * @param name The name of the grammar features. + * @param values The list of features. + */ LanguageGrammarFeatures_GrammarFeatures(const std::u16string& name, const std::vector<::inflection::lang::features::LanguageGrammarFeatures_Feature>& values); public: /**