comment key use

include/nana/gui/widgets/listbox.hpp

@@ -514,8 +514,11 @@ By \a clicking on a header the list get \a reordered, first up, and then down al
 		void append(std::initializer_list<nana::string>); ///<Appends categories at the end
 		cat_proxy insert(cat_proxy, nana::string);
 		cat_proxy at(size_type pos) const;
+
+        /// add categories in order when use a key?
 		listbox& ordered_categories(bool);
 
+        /// return a proxy to tha cat with the key or create a new one in the right order
 		template<typename Key>
 		cat_proxy operator[](const Key & ck)
 		{

include/nana/key_type.hpp

@@ -22,10 +22,10 @@ namespace nana
 			virtual ~key_interface(){}
 
 			virtual bool same_type(const key_interface*) const = 0;
-			virtual bool compare(const key_interface*) const = 0;
+			virtual bool compare(const key_interface*) const = 0; ///< is this key less than right key? [call it less(rk), less_than(rk) or compare_less(rk)?: if (lk.less_than(rk )) ]
 		};	//end class key_interface
 
-		//Use less compare for equal compare
+		//Use less compare for equal compare [call it equal_by_less()?]
 		inline bool pred_equal_by_less(const key_interface * left, const key_interface* right)
 		{
 			return (left->compare(right) == false) && (right->compare(left) == false);

source/gui/widgets/listbox.cpp

@@ -834,20 +834,21 @@ namespace nana
 					return sorted_reverse_;
 				}
 
-				///Append a new category with a specified name.
+				///Append a new category with a specified name and return a pointer to it.
 				category_t* create_cat(nana::string&& text)
 				{
 					list_.emplace_back(std::move(text));
 					return &list_.back();
 				}
-
+                /// just append a list of new cat.
 				void create_cat(const std::initializer_list<nana::string>& args)
 				{
 					for (auto & arg : args)
 						list_.emplace_back(arg);
 				}
 
-				category_t* create_cat(std::shared_ptr<nana::detail::key_interface> ptr)
+		        /// will use the key to insert new cat before the first cat with compare less than the key, or at the end of the list of cat and return a ref to that new cat.  ?
+                category_t* create_cat(std::shared_ptr<nana::detail::key_interface> ptr)
 				{
 					for (auto i = list_.begin(); i != list_.end(); ++i)
 					{
@@ -863,7 +864,7 @@ namespace nana
 					list_.back().key_ptr = ptr;
 					return &list_.back();
 				}
-
+                /// add a new cat created at "pos" and return a ref to it 
 				category_t* create_cat(std::size_t pos, nana::string&& text)
 				{
 #if defined(NANA_LINUX) || defined(NANA_MINGW)