Icon-O-Matic: Document the importer/exporter classes

Change-Id: I04e920e873efffa0756bb7d0391ac0f898128204
Reviewed-on: https://review.haiku-os.org/c/haiku/+/6465
Tested-by: Commit checker robot <[email protected]>
Reviewed-by: Adrien Destugues <[email protected]>

src/apps/icon-o-matic/import_export/Exporter.h

@@ -22,12 +22,17 @@ _END_ICON_NAMESPACE
 
 _USING_ICON_NAMESPACE
 
-
+/*! Base class for all exporters to implement. */
 class Exporter {
  public:
 								Exporter();
 	virtual						~Exporter();
 
+	/*! Export the Document to the specified entry_ref.
+		Spawns a separate thread to do the actual exporting.
+		Uses the virtual Export function defined after this function to do the
+		actual export.
+	*/
 			status_t			Export(Document* document,
 									   const entry_ref& ref);
 
@@ -36,6 +41,9 @@ class Exporter {
 
 	virtual	const char*			MIMEType() = 0;
 
+	/*! If \a selfDestroy is true, class deletes itself when export thread is
+		finished.
+	*/
 			void				SetSelfDestroy(bool selfDestroy);
 
 			void				WaitForExportThread();

src/apps/icon-o-matic/import_export/Importer.h

@@ -20,7 +20,12 @@ _END_ICON_NAMESPACE
 
 _USING_ICON_NAMESPACE
 
+/*! Base class providing facilities for all importers.
+	Child classes should have an Import function taking parameters relavent to
+	the thing they import.
 
+	\note Some importers are in the icon library.
+*/
 class Importer {
  public:
 								Importer();
@@ -28,9 +33,17 @@ class Importer {
 
 			status_t			Init(Icon* icon);
 
+	/*!
+		Sometimes the thing being imported is being imported into a file that
+		already has items. This means that style index zero and path index zero
+		are likely already taken. These functions take in a zero-based index
+		and offset them to a previously unused style/path index.
+	*/
+
+	//! @{
 			int32				StyleIndexFor(int32 savedIndex) const;
 			int32				PathIndexFor(int32 savedIndex) const;
-
+	//! @}
  private:
 			int32				fStyleIndexOffset;
 			int32				fPathIndexOffset;

src/apps/icon-o-matic/import_export/bitmap/BitmapExporter.h

@@ -11,6 +11,11 @@
 
 #include "Exporter.h"
 
+/*! Exports to an arbitrary image format.
+	Uses BBitmap and a Translator to turn an image into the desired format.
+
+	\note Currently only exports to the PNG format.
+*/
 class BitmapExporter : public Exporter {
  public:
 								BitmapExporter(uint32 size);

src/apps/icon-o-matic/import_export/flat_icon/FlatIconExporter.h

@@ -47,6 +47,7 @@ class PointHash {
 typedef hash_set<BPoint, PointHash> PointSet;
 #endif
 
+/*! Export to HVIF file or to an existing file's attribute. */
 class FlatIconExporter : public Exporter {
  public:
 								FlatIconExporter();
@@ -58,7 +59,7 @@ class FlatIconExporter : public Exporter {
 
 	virtual	const char*			MIMEType();
 
-	// FlatIconExporter
+	/*! Export to file attribute */
 	status_t					Export(const Icon* icon, BNode* node,
 									   const char* attrName);
 

src/apps/icon-o-matic/import_export/flat_icon/RDefExporter.h

@@ -11,6 +11,7 @@
 
 #include "FlatIconExporter.h"
 
+/*! Exports HVIF file data to an RDef file. */
 class RDefExporter : public FlatIconExporter {
  public:
 								RDefExporter();

src/apps/icon-o-matic/import_export/flat_icon/SourceExporter.h

@@ -11,6 +11,7 @@
 
 #include "FlatIconExporter.h"
 
+/*! Exports HVIF file data into a C/C++ array */
 class SourceExporter : public FlatIconExporter {
  public:
 								SourceExporter();

src/apps/icon-o-matic/import_export/message/MessageExporter.h

@@ -24,7 +24,7 @@ _BEGIN_ICON_NAMESPACE
 	class VectorPath;
 _END_ICON_NAMESPACE
 
-
+/** Exporter for the native Icon-O-Matic save format. */
 class MessageExporter : public Exporter {
  public:
 								MessageExporter();

src/apps/icon-o-matic/import_export/styled_text/StyledTextImporter.h

@@ -31,6 +31,10 @@ struct style_map {
 	Style *style;
 };
 
+/*! Turns text into its associated paths and shapes.
+	Coloring can also be imported from applications, such as StyledEdit, that
+	specify it.
+*/
 class StyledTextImporter : public Importer {
  public:
 								StyledTextImporter();

src/apps/icon-o-matic/import_export/svg/DocumentBuilder.h

@@ -28,7 +28,7 @@ _END_ICON_NAMESPACE
 
 _USING_ICON_NAMESPACE
 
-
+/*! Puts the information from an NSVGimage class into an Icon class. */
 class DocumentBuilder {
  public: