Some Doxygen comments.

15 files changed, 80 insertions, 7 deletions

diff --git a/src/colour.h b/src/colour.h
index 4989277..673bb9f 100644
--- a/src/colour.h
+++ b/src/colour.h
@@ -24,6 +24,9 @@
 
 namespace sub {
 
+/** @class Colour
+ *  @brief An RGB colour.
+ */
 class Colour
 {
 public:
diff --git a/src/dcp_reader.cc b/src/dcp_reader.cc
index a5fdd00..b938b6c 100644
--- a/src/dcp_reader.cc
+++ b/src/dcp_reader.cc
@@ -39,6 +39,9 @@ namespace sub {
 
 class DCPFont;
 
+/** @class DCPText
+ *  @brief A DCP subtitle <Text> node.
+ */
 class DCPText
 {
 public:
@@ -67,6 +70,9 @@ public:
 	list<shared_ptr<DCPFont> > font_nodes;
 };
 
+/** @class DCPSubtitle
+ *  @brief A DCP subtitle &lt;Subtitle&gt; node.
+ */
 class DCPSubtitle 
 {
 public:
@@ -121,6 +127,9 @@ private:
 	}
 };
 
+/** @class DCPFont
+ *  @brief A DCP subtitle &lt;Font&gt; node.
+ */
 class DCPFont 
 {
 public:
@@ -193,6 +202,9 @@ public:
 	list<shared_ptr<DCPText> > text_nodes;
 };
 
+/** @class DCPLoadFont
+ *  @brief A DCP subtitle &lt;LoadFont&gt; node.
+ */
 class DCPLoadFont 
 {
 public:
@@ -207,6 +219,9 @@ public:
 	string uri;
 };
 
+/** @class DCPReader::ParseState
+ *  @brief Holder of state for use while reading DCP subtitles.
+ */
 struct DCPReader::ParseState {
 	list<shared_ptr<DCPFont> > font_nodes;
 	list<shared_ptr<DCPText> > text_nodes;
@@ -249,6 +264,9 @@ DCPReader::font_id_to_name (string id) const
 	return (*i)->uri;
 }
 
+/** @class DCPReader
+ *  @brief A class to read DCP subtitles.
+ */
 DCPReader::DCPReader (istream& in)
 {
 	shared_ptr<cxml::Document> xml (new cxml::Document ("DCSubtitle"));
diff --git a/src/dcp_reader.h b/src/dcp_reader.h
index aa8df7f..70b7d4f 100644
--- a/src/dcp_reader.h
+++ b/src/dcp_reader.h
@@ -31,6 +31,9 @@ class DCPText;
 class DCPSubtitle;
 class DCPLoadFont;
 
+/** @class DCPReader
+ *  @brief A class which reads DCP subtitles.
+ */
 class DCPReader : public Reader
 {
 public:
diff --git a/src/exceptions.h b/src/exceptions.h
index 5e784ee..f2f1246 100644
--- a/src/exceptions.h
+++ b/src/exceptions.h
@@ -22,6 +22,9 @@
 
 namespace sub {
 
+/** @class XMLError
+ *  @brief An error raised when reading an XML file.
+ */
 class XMLError : public std::exception
 {
 public:
@@ -37,7 +40,10 @@ private:
 	/** error message */
 	std::string _message;
 };
-	
+
+/** @class STLError
+ *  @brief An error raised when reading a binary STL file.
+ */
 class STLError : public std::exception
 {
 public:
diff --git a/src/font_size.h b/src/font_size.h
index 2be2434..0b4b357 100644
--- a/src/font_size.h
+++ b/src/font_size.h
@@ -21,7 +21,13 @@
 #define LIBSUB_FONT_SIZE_H
 
 namespace sub {
-	
+
+/** @class FontSize
+ *  @brief A description of a font's size in one of a number of ways.
+ *
+ *  An object of this class holds a font's size in one way, and it can convert
+ *  to another on supply of the required conversion parameters.
+ */
 class FontSize
 {
 public:
diff --git a/src/frame_time.h b/src/frame_time.h
index aa24931..1a97e63 100644
--- a/src/frame_time.h
+++ b/src/frame_time.h
@@ -25,7 +25,7 @@
 namespace sub {
 
 /** @class FrameTime
- *  @brief A time in hours, minutes, seconds and frames.
+ *  @brief A time stored in hours, minutes, seconds and frames.
  */
 class FrameTime
 {
diff --git a/src/metric_time.h b/src/metric_time.h
index 226c0a1..016d7c1 100644
--- a/src/metric_time.h
+++ b/src/metric_time.h
@@ -26,7 +26,7 @@
 namespace sub {
 
 /** @class MetricTime
- *  @brief A time held in milliseconds.
+ *  @brief A time stored in milliseconds.
  */
 class MetricTime
 {
diff --git a/src/raw_subtitle.h b/src/raw_subtitle.h
index ffdc669..8a8ac7f 100644
--- a/src/raw_subtitle.h
+++ b/src/raw_subtitle.h
@@ -34,6 +34,9 @@
 
 namespace sub {
 
+/** @class RawSubtitle
+ *  @brief A bit of a subtitle, created with no regard for any nearby bits.
+ */
 class RawSubtitle
 {
 public:
diff --git a/src/reader.h b/src/reader.h
index 1237bb5..989ad58 100644
--- a/src/reader.h
+++ b/src/reader.h
@@ -27,6 +27,9 @@
 
 namespace sub {
 
+/** @class Reader
+ *  @brief Parent for classes which can read particular subtitle formats.
+ */
 class Reader
 {
 public:
diff --git a/src/stl_binary_reader.h b/src/stl_binary_reader.h
index 0e3c7cf..9c2e61f 100644
--- a/src/stl_binary_reader.h
+++ b/src/stl_binary_reader.h
@@ -23,6 +23,9 @@
 
 namespace sub {
 
+/** @class STLBinaryReader
+ *  @brief A class to read binary STL files.
+ */
 class STLBinaryReader : public Reader
 {
 public:
diff --git a/src/stl_binary_tables.h b/src/stl_binary_tables.h
index 3118b02..de9634b 100644
--- a/src/stl_binary_tables.h
+++ b/src/stl_binary_tables.h
@@ -167,6 +167,9 @@ enum Comment {
 	COMMENT_YES
 };
 
+/** @class STLBinaryCode
+ *  @brief A value of some STL parameter and a human-readable description of what it means.
+ */
 template<class T>
 class STLBinaryCode
 {
@@ -184,6 +187,9 @@ public:
 	std::string description;
 };
 
+/** @class STLBinaryTables
+ *  @brief A set of conversion tables for STL binary files.
+ */
 class STLBinaryTables
 {
 public:
diff --git a/src/stl_text_reader.h b/src/stl_text_reader.h
index b84e8b8..f6eb2a3 100644
--- a/src/stl_text_reader.h
+++ b/src/stl_text_reader.h
@@ -22,6 +22,9 @@
 
 namespace sub {
 
+/** @class STLTextReader
+ *  @brief A class to read textual STL files
+ */
 class STLTextReader : public Reader
 {
 public:
diff --git a/src/subtitle.h b/src/subtitle.h
index 795b11e..6afdc51 100644
--- a/src/subtitle.h
+++ b/src/subtitle.h
@@ -35,7 +35,11 @@
 
 namespace sub {
 
-/** A piece of text with a single font, style, size etc. */       
+/** @class Block
+ *  @brief A block of text within a subtitle's line
+ *
+ *  This represents a block of text which has a particular style (font, size, effect, colour etc.)
+ */
 class Block
 {
 public:
@@ -65,7 +69,11 @@ public:
 	bool underline; ///< true to underline
 };
 
-/** A line of text */
+/** @class Line
+ *  @brief A line of text within a subtitle.
+ *
+ *  This represents a line of text which has a particular vertical position.
+ */
 class Line
 {
 public:
@@ -82,6 +90,12 @@ public:
 	bool same_metadata (RawSubtitle) const;
 };
 
+/** @class Subtitle
+ *  @brief A subtitle which has been collected into lines and blocks.
+ *
+ *  This represents a chunk of text which appears and disappears at some particular
+ *  times.
+ */
 class Subtitle
 {
 public:
diff --git a/src/time_pair.h b/src/time_pair.h
index 9b9c357..85d79e5 100644
--- a/src/time_pair.h
+++ b/src/time_pair.h
@@ -26,6 +26,9 @@
 
 namespace sub {
 
+/** @class TimePair
+ *  @brief A time, expressed either in metric (h:m:s:ms) or frames (h:m:s:f).
+ */
 class TimePair
 {
 public:
diff --git a/src/vertical_position.h b/src/vertical_position.h
index 6885f0e..6a0fff4 100644
--- a/src/vertical_position.h
+++ b/src/vertical_position.h
@@ -25,7 +25,9 @@
 
 namespace sub {
 
-/** Vertical position of the baseline of some text */
+/** @class VerticalPosition
+ *  @brief Vertical position of the baseline of some text, expressed in one of a number of ways.
+ */
 class VerticalPosition
 {
 public: