Some doc improvements.

9 files changed, 64 insertions, 3 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
index cb03388..829fc35 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -743,7 +743,7 @@ WARN_LOGFILE           =
 # spaces.
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src
+INPUT                  = src doc
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -763,7 +763,7 @@ INPUT_ENCODING         = UTF-8
 # *.md, *.mm, *.dox, *.py, *.f90, *.f, *.for, *.tcl, *.vhd, *.vhdl, *.ucf,
 # *.qsf, *.as and *.js.
 
-FILE_PATTERNS          =
+FILE_PATTERNS          = *.cc *.h *.txt
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
 # be searched for input files as well.
diff --git a/doc/mainpage.txt b/doc/mainpage.txt
new file mode 100644
index 0000000..642cff6
--- /dev/null
+++ b/doc/mainpage.txt
@@ -0,0 +1,36 @@
+/*!
+
+@mainpage libsub
+
+libsub is a library to read and write subtitles in a variety of formats.  It can be used to read subtitles for
+processing, to write them or to convert between formats.
+
+The current version has reasonable support for the following subtitle formats:
+- Digital Cinema Package (DCP) XML
+- SubRip (.srt)
+- EBU-STL text and binary
+
+
+Reading subtitles
+--
+
+The basic process is:
+
+    shared_ptr<sub::Reader> reader = reader_factory (filename);
+    list<sub::Subtitle> subs = collect<list<sub::Subtitle> > (reader->subtitles ());
+
+We first have:
+
+    shared_ptr<sub::Reader> reader = reader_factory (filename);
+ 
+This looks at the extension of `filename' and, if necessary, its header, and guesses
+what format it is in.  Based on the format it creates an appropriate Reader object.
+This reader object can then return its subtitles using
+
+    reader->subtitles ();
+
+    
+
+
+
+*/
diff --git a/make_docs b/make_docs
new file mode 100755
index 0000000..c542326
--- /dev/null
+++ b/make_docs
@@ -0,0 +1,2 @@
+#!/bin/bash
+doxygen doc/Doxyfile
diff --git a/src/collect.h b/src/collect.h
index 9f3db63..34f81aa 100644
--- a/src/collect.h
+++ b/src/collect.h
@@ -24,7 +24,10 @@
 #include "raw_subtitle.h"
 
 namespace sub {
-	
+
+/** Collect sub::RawSubtitle objects into sub::Subtitles.
+ *  This method is templated so that any container type can be used for the result.
+ */
 template <class T>
 T
 collect (std::list<RawSubtitle> raw)
diff --git a/src/stl_binary_writer.cc b/src/stl_binary_writer.cc
index 6e8f598..aa9a032 100644
--- a/src/stl_binary_writer.cc
+++ b/src/stl_binary_writer.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/stl_binary_writer.cc
+ *  @brief Writer for STL binary files.
+ */
+
 #include "stl_binary_writer.h"
 #include "subtitle.h"
 #include "iso6937.h"
diff --git a/src/stl_binary_writer.h b/src/stl_binary_writer.h
index b4ab960..4986afb 100644
--- a/src/stl_binary_writer.h
+++ b/src/stl_binary_writer.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/stl_binary_writer.h
+ *  @brief Writer for STL binary files.
+ */
+
 #ifndef LIBSUB_STL_BINARY_WRITER_H
 #define LIBSUB_STL_BINARY_WRITER_H
 
diff --git a/src/time_pair.cc b/src/time_pair.cc
index 9fc7974..35ba3d0 100644
--- a/src/time_pair.cc
+++ b/src/time_pair.cc
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/time_pair.cc
+ *  @brief TimePair class.
+ */
+
 #include "time_pair.h"
 
 using std::ostream;
diff --git a/src/time_pair.h b/src/time_pair.h
index d4b2c09..6265480 100644
--- a/src/time_pair.h
+++ b/src/time_pair.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/time_pair.h
+ *  @brief TimePair class.
+ */
+
 #ifndef LIBSUB_TIME_PAIR_H
 #define LIBSUB_TIME_PAIR_H
 
diff --git a/src/xml.h b/src/xml.h
index 568eba5..d62dbd6 100644
--- a/src/xml.h
+++ b/src/xml.h
@@ -17,6 +17,10 @@
 
 */
 
+/** @file  src/xml.h
+ *  @brief Some useful XML helper functions.
+ */
+
 #ifndef LIBSUB_XML_H
 #define LIBSUB_XML_H