Skip to content

Commit 23cc5bb

Browse files
FrankYFTanggrhoten
FrankYFTang
and
grhoten
authored
Fix the doxygen warnings (issue 147) (#159)
* Update InflectableStringConcept.hpp * Update SemanticConceptList.hpp * Update SemanticFeature.hpp * Update SemanticFeature.hpp * Update SemanticFeatureConceptBase.hpp * Update SemanticFeatureModel.hpp * Update SemanticValue.hpp * Update SpeakableString.hpp * Update XMLParseException.hpp * Update LanguageGrammarFeatures_Feature.hpp * Update LanguageGrammarFeatures_GrammarCategory.hpp * Update LanguageGrammarFeatures_GrammarFeatures.hpp * Update LanguageGrammarFeatures_GrammarFeatures.hpp * Update LanguageGrammarFeatures_GrammarFeatures.hpp * Update inflection/src/inflection/dialog/InflectableStringConcept.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeature.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeature.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureModel.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticValue.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SpeakableString.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/exception/XMLParseException.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp Co-authored-by: George Rhoten <[email protected]> * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update SemanticFeature.hpp formatting * Update inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp Co-authored-by: George Rhoten <[email protected]> * Update SemanticFeatureConceptBase.hpp formatting * Update SemanticFeatureModel.hpp * Update LanguageGrammarFeatures_Feature.hpp * Update SemanticFeature.hpp * Update LanguageGrammarFeatures_GrammarCategory.hpp * Update LanguageGrammarFeatures_GrammarFeatures.hpp * Update SemanticFeatureConceptBase.hpp * Update SemanticFeature.hpp * Update LanguageGrammarFeatures_GrammarFeatures.hpp * Update LanguageGrammarFeatures_GrammarCategory.hpp * Update LanguageGrammarFeatures_GrammarCategory.hpp --------- Co-authored-by: George Rhoten <[email protected]>
1 parent 53e72e3 commit 23cc5bb

11 files changed

+179
-11
lines changed

‎inflection/src/inflection/dialog/InflectableStringConcept.hpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ class INFLECTION_CLASS_API inflection::dialog::InflectableStringConcept
4040
* @return true when the value is empty.
4141
*/
4242
bool isExists() const override;
43+
/**
44+
* Return a string helpful for debugging purposes.
45+
*/
4346
::std::u16string toString() const override;
4447

4548
private:

‎inflection/src/inflection/dialog/SemanticConceptList.hpp‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,17 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticConceptList
3333
bool avoidAffixRedundancy { true };
3434

3535
public:
36+
/**
37+
* Put constraint feature and value into the SemanticConceptList.
38+
* @param feature the feature of the constraint to be added.
39+
* @param featureValue the value of the constraint.
40+
*/
3641
void putConstraint(const SemanticFeature& feature, ::std::u16string_view featureValue) override;
37-
void clearConstraint(const SemanticFeature& feature) override;
42+
/**
43+
* Clean the constraint feature in the SemanticConceptList.
44+
* @param feature the feature of the constraint to be clearn.
45+
*/
46+
void clearConstraint(const SemanticFeature& feature) override;
3847
void reset() override;
3948

4049
public: /* protected */

‎inflection/src/inflection/dialog/SemanticFeature.hpp‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeature
2020
/// @endcond
2121

2222
public:
23+
/**
24+
* Metadata about how a SemanticFeature is bounded.
25+
*/
2326
enum Type {
2427
NoValue,
2528
BoundedValue,
@@ -60,13 +63,31 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeature
6063
*/
6164
virtual const ::std::u16string& getName() const;
6265
/**
63-
* Returns the possible values of this SemanticFeature. Only bounded SemanticFeatures can have a non-empty set of bounded values.
66+
* Returns the possible values of this SemanticFeature. Only bounded SemanticFeatures
67+
* can have a non-empty set of bounded values.
6468
*/
6569
virtual const ::std::set<::std::u16string>& getBoundedValues() const;
70+
/**
71+
* True if this semantic feature can be referenced by the bounded values directly or
72+
* aliased without specifying the name.
73+
*/
6674
virtual bool isAliased() const;
6775
bool operator<(const SemanticFeature& other) const;
76+
/**
77+
* Returns true when both objects refer to the same semantic feature, with the same
78+
* name.
79+
* @param other The semantic feature object to be compared with this.
80+
* @return True if the two semantic feature are the same, false otherwise.
81+
*/
6882
bool operator==(const SemanticFeature& other) const;
6983

84+
/**
85+
* Construct the SemanticFeature from the name, type, bounded values.
86+
* @param name The name of the SemanticFeature.
87+
* @param type The type of the SemanticFeature.
88+
* @param boundedValues The set of values bounded to the feature.
89+
* @param aliased To indicate the feature is an alias.
90+
*/
7091
SemanticFeature(const ::std::u16string& name, Type type, const ::std::set<::std::u16string>& boundedValues, bool aliased);
7192
/**
7293
* The copy constructor

‎inflection/src/inflection/dialog/SemanticFeatureConceptBase.hpp‎

Lines changed: 39 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,18 +27,49 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase
2727
private: /* package */
2828
const SemanticFeatureModel* model { };
2929
protected: /* package */
30+
/**
31+
* All the constraints
32+
*/
3033
::std::map<SemanticFeature, ::std::u16string> constraints { };
3134

3235
public: /* protected */
3336
/**
3437
* Returns the SemanticFeatureModel used to create this string.
3538
*/
3639
virtual const SemanticFeatureModel* getModel() const;
40+
/**
41+
* Get the value of the semantic feature.
42+
* @param feature The semantic feature object.
43+
* @return The value of the constraint feature.
44+
*/
3745
virtual const ::std::u16string* getConstraint(const SemanticFeature& feature) const;
46+
/**
47+
* Check if the semantic feature has been added as a constraint.
48+
* @param feature The semantic feature object.
49+
* @return True if the semantic feature is in this, false otherwise.
50+
*/
3851
virtual bool hasConstraint(const SemanticFeature& feature) const;
52+
/**
53+
* Add a semantic feature with a value as a constraint.
54+
* @param feature The semantic feature object of the constraint to be added.
55+
* @param featureValue The value of the feature.
56+
*/
3957
virtual void putConstraint(const SemanticFeature& feature, ::std::u16string_view featureValue);
58+
/**
59+
* Add a semantic feature with a value as a constraint by the name of the SemanticFeature.
60+
* @param featureName The name of the feature.
61+
* @param featureValue The value of the feature.
62+
*/
4063
virtual void putConstraintByName(::std::u16string_view featureName, ::std::u16string_view featureValue);
64+
/**
65+
* Clear the specified semantic constraint feature.
66+
* @param feature The semantic feature of the constraint to be cleared.
67+
*/
4168
virtual void clearConstraint(const SemanticFeature& feature);
69+
/**
70+
* Clear the specified semantic constraint feature by the given feature name.
71+
* @param featureName The name of the constraint to be cleared.
72+
*/
4273
virtual void clearConstraintByName(::std::u16string_view featureName);
4374
/**
4475
* Returns {@code true} if a value exists for the given constraints
@@ -53,11 +84,15 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase
5384
*/
5485
virtual SpeakableString* getFeatureValue(const SemanticFeature& feature) const = 0;
5586
/**
56-
* Returns the String value of the specified feature for this concept, given its current constraints.
87+
* Returns the String value of the specified feature for this concept, given its
88+
* current constraints.
5789
* The featureName will be automatically converted to a SemanticFeature for lookup.
5890
*/
5991
virtual SpeakableString* getFeatureValueByName(::std::u16string_view featureName) const;
6092
protected: /* protected */
93+
/**
94+
* The semantic feature for the spoken form of a string.
95+
*/
6196
virtual const SemanticFeature* getSpeakFeature() const;
6297

6398
public:
@@ -68,8 +103,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureConceptBase
68103

69104
/**
70105
* This constructor for the abstract class should be called by the subclasses.
71-
* @param model The SemanticFeatureModel that provides all of the features, valid constraints, default functions
72-
* and other relevant information for a given language.
106+
* @param model The SemanticFeatureModel that provides all of the features,
107+
* valid constraints, default functions
108+
* and other relevant information for a given language.
73109
*/
74110
explicit SemanticFeatureConceptBase(const SemanticFeatureModel* model);
75111
/**

‎inflection/src/inflection/dialog/SemanticFeatureModel.hpp‎

Lines changed: 41 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final
3737
std::unique_ptr<DefaultDisplayFunction> defaultDisplayFunction;
3838

3939
public:
40+
/**
41+
* The name of the speak semantic feature.
42+
*/
4043
static constexpr auto SPEAK = u"speak";
4144

4245
/**
@@ -47,28 +50,56 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final
4750
* Returns the SemanticFeatureModel_DisplayData associated with the semantic value in this SemanticFeatureModel
4851
*/
4952
const SemanticFeatureModel_DisplayData* getDisplayData(const SemanticValue& semantic) const;
53+
/**
54+
* Return the semantic feature by the name.
55+
* @param name The name of the semantic feature.
56+
*/
5057
const SemanticFeature* getFeature(::std::u16string_view name) const;
58+
/**
59+
* If a feature name is aliasable, return the associated semantic feature and its value.
60+
* If a semantic feature can be more than one name, the value will have the canonical name.
61+
* This can happen if the semantic feature has been deprecated, or has more than one known
62+
* name for the value.
63+
* @param name The name of the semantic feature.
64+
* @return The semantic feature will be null if no alias was found.
65+
*/
5166
::std::pair<::inflection::dialog::SemanticFeature*, ::std::u16string> getFeatureAlias(::std::u16string_view name) const;
5267
/**
5368
* Returns the locale created with this SemanticFeatureModel.
5469
*/
5570
const util::ULocale& getLocale() const;
71+
/**
72+
* Returns the registered feature function for the requested semantic feature.
73+
* @param feature The feature to request.
74+
* @return Returns null if no feature function exists.
75+
*/
5676
const DefaultFeatureFunction* getDefaultFeatureFunction(const SemanticFeature& feature) const;
77+
/**
78+
* Register a default feature function for a semantic feature.
79+
* @param feature The feature to register the function for.
80+
* @param function The feature function to call for the semantic feature. This
81+
* SemanticFeatureModel will adopt ownership of this function, and it will be
82+
* deleted when this SemanticFeatureModel is deleted.
83+
*/
5784
void putDefaultFeatureFunction(const SemanticFeature& feature, DefaultFeatureFunction* function);
5885
/**
59-
* This function works the same way as putDefaultFeatureFunction, but an exception is thrown if the feature is unknown.
86+
* This function works the same way as putDefaultFeatureFunction, but an exception is
87+
* thrown if the feature is unknown.
6088
* @param feature The name of the SemanticFeature in this SemanticFeatureModel.
61-
* @param function The function to derive the specified SemanticFeature for the locale when it's not specified by available SemanticFeatureModel_DisplayData.
89+
* @param function The function to derive the specified SemanticFeature for the locale when
90+
* it's not specified by available SemanticFeatureModel_DisplayData.
6291
*/
6392
void putDefaultFeatureFunctionByName(::std::u16string_view feature, DefaultFeatureFunction* function);
6493
/**
65-
* Returns the function is used for inflecting phrases when no constraints match the available SemanticFeatureModel_DisplayData.
94+
* Returns the function is used for inflecting phrases when no constraints match the available
95+
* SemanticFeatureModel_DisplayData.
6696
* When it's null, then there is no way to inflect phrases from the constraints.
6797
* @see getDisplayData
6898
*/
6999
const DefaultDisplayFunction* getDefaultDisplayFunction() const;
70100
/**
71-
* This function is used for inflecting phrases when no constraints match the available SemanticFeatureModel_DisplayData.
101+
* This function is used for inflecting phrases when no constraints match the available
102+
* SemanticFeatureModel_DisplayData.
72103
* Normally this does not need to be set.
73104
* @see getDisplayData
74105
*/
@@ -82,6 +113,12 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticFeatureModel final
82113
* Creates a default SemanticFeatureModel for a given locale without any display data.
83114
*/
84115
explicit SemanticFeatureModel(const ::inflection::util::ULocale& locale);
116+
/**
117+
* Creates a SemanticFeatureModel for a given locale with a mapping of display data used for
118+
* constructing things like a SemanticConcept.
119+
* @param locale The locale.
120+
* @param semanticValueMap The mapping of a semantic value to display data.
121+
*/
85122
SemanticFeatureModel(const ::inflection::util::ULocale& locale, const ::std::map<SemanticValue, SemanticFeatureModel_DisplayData>& semanticValueMap);
86123
/**
87124
* Destructor

‎inflection/src/inflection/dialog/SemanticValue.hpp‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,9 @@ class INFLECTION_CLASS_API inflection::dialog::SemanticValue
4747
*/
4848
std::strong_ordering operator<=>(const SemanticValue&) const;
4949

50+
/**
51+
* Construct a SemanticValue by a label and a string value.
52+
*/
5053
SemanticValue(const ::std::u16string& label, const ::std::u16string& string);
5154
/**
5255
* Destructor

‎inflection/src/inflection/dialog/SpeakableString.hpp‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,11 +44,39 @@ class INFLECTION_CLASS_API inflection::dialog::SpeakableString
4444
*/
4545
virtual bool speakEqualsPrint() const;
4646

47+
/**
48+
* Return a string helpful for debugging purposes.
49+
*/
4750
::std::u16string toString() const override;
51+
/**
52+
* Returns true when both objects refer to the speakable string, with the same print and speak string.
53+
* @param o The speakable string object to be compared with this.
54+
* @return True if the two speakable string are the same, false otherwise.
55+
*/
4856
bool operator==(const ::inflection::dialog::SpeakableString& o) const;
57+
/**
58+
* Equivalent to the inverse of operator==.
59+
* @param o The speakable string object to be compared with this.
60+
* @return True if the two display value are not the same, false otherwise.
61+
*/
4962
bool operator!=(const ::inflection::dialog::SpeakableString& o) const;
63+
/**
64+
* Create a new speakable string by appened other to this.
65+
* @param o the speakable string to be appened with this.
66+
* @return the result speakable string object.
67+
*/
5068
SpeakableString operator+(const ::inflection::dialog::SpeakableString& o) const;
69+
/**
70+
* Assigns a speakable string to this.
71+
* @param o the speakable string to be assigned to this.
72+
* @return the result speakable string object.
73+
*/
5174
SpeakableString& operator=(const ::inflection::dialog::SpeakableString& o);
75+
/**
76+
* Appends a speakable string to this.
77+
* @param o the speakable string to be appended to this.
78+
* @return the result speakable string object.
79+
*/
5280
SpeakableString& operator+=(const ::inflection::dialog::SpeakableString& o);
5381

5482
/**

‎inflection/src/inflection/exception/XMLParseException.hpp‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,10 @@ class INFLECTION_CLASS_API inflection::exception::XMLParseException
2222

2323
public:
2424
XMLParseException();
25+
/**
26+
* Construct an XMLParseException with a message.
27+
* @param message The debugging message of this XML parse exception.
28+
*/
2529
explicit XMLParseException(const std::u16string& message);
2630
~XMLParseException() override;
2731
};

‎inflection/src/inflection/lang/features/LanguageGrammarFeatures_Feature.hpp‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,13 @@ class INFLECTION_CLASS_API inflection::lang::features::LanguageGrammarFeatures_F
3939
virtual std::map<std::u16string, std::u16string> getConstraints() const;
4040

4141
public: /* package */
42+
/**
43+
* Construct a feature by value and a mapping of constraints.
44+
* @param value the name of the feature.
45+
* @param constraints The constraints that are valid for the value. This map contains
46+
* grammatical category name mapped to the specific value valid for the
47+
* grammatical category.
48+
*/
4249
LanguageGrammarFeatures_Feature(const std::u16string& value, const std::map<std::u16string, std::u16string>& constraints);
4350
/**
4451
* Destructor

‎inflection/src/inflection/lang/features/LanguageGrammarFeatures_GrammarCategory.hpp‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,15 @@ class INFLECTION_CLASS_API inflection::lang::features::LanguageGrammarFeatures_G
5959
* @param grammemeValue Use <code>getValues()</code> to get the list of values that can be used as an argument.
6060
*/
6161
std::multimap<std::u16string, std::u16string> getGrammemeDependenciesForValue(std::u16string_view grammemeValue) const;
62-
virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarCategory& o) const;
62+
63+
/**
64+
* Compares the name of this grammar category with the other..
65+
* @param other The grammar category object to be compared with this.
66+
* @return the value 0 if the name of the argument other is equal to the name of this; a value -1 if the name
67+
* of this is lexicographically less than the name of the argument other; and a value 1 if the name
68+
* of this is lexicographically greater than the name of the argument other.
69+
*/
70+
virtual int32_t compareTo(const LanguageGrammarFeatures_GrammarCategory& other) const;
6371
bool operator<(const LanguageGrammarFeatures_GrammarCategory& other) const;
6472

6573

0 commit comments

Comments
 (0)