diff --git a/BUILD b/BUILD
index bde6f9b6a..4cef92f72 100644
--- a/BUILD
+++ b/BUILD
@@ -22,6 +22,10 @@ scons verbose=y
 2) Targets
 ----------
 
+- doc: build the doxygen documentation.
+Example:
+scons doc
+
 - dbg-shared: a debug build using shared libraries.
   The files are built in 'build-dir/dbg-shared/'.
 Example:
diff --git a/src/common/pcap-writer.h b/src/common/pcap-writer.h
index 13f6b177c..28e162e02 100644
--- a/src/common/pcap-writer.h
+++ b/src/common/pcap-writer.h
@@ -51,7 +51,9 @@ public:
     /**
      * Write a pcap header in the output file which specifies
      * that the content of the file will Packets with
-     * Ethernet/LLC/SNAP encapsulation.
+     * Ethernet/LLC/SNAP encapsulation. This method should
+	 * be invoked before ns3::PcapWriter::writePacket and after
+	 * ns3::PcapWriter::open.
      */
     void writeHeaderEthernet (void);
 
diff --git a/src/core/system-file.h b/src/core/system-file.h
index 6e2a6b316..bc43af596 100644
--- a/src/core/system-file.h
+++ b/src/core/system-file.h
@@ -28,12 +28,45 @@ namespace ns3 {
 
 class SystemFilePrivate;
 
+/**
+ * \brief os-independent file creation and writing
+ *
+ * Create a file and write data to this file.
+ */
 class SystemFile {
 public:
+	/**
+	 * This method does not create or open any
+	 * file on disk.
+	 */
     SystemFile ();
+	/**
+	 * If a file has been opened, it is closed by
+	 * this destructor.
+	 */
     ~SystemFile ();
 
+	/**
+	 * \param filename name of file to open
+	 *
+	 * Open a file for writing. If the file does not
+	 * exist, it is created. If it exists, it is 
+	 * emptied first.
+	 */
     void open (char const *filename);
+	/**
+	 * \param buffer data to write
+	 * \param size size of data to write
+	 *
+	 * Write data in file on disk. This method cannot fail:
+	 * it will write _all_ the data to disk. This method does not
+	 * perform any data caching and forwards the data
+	 * to the OS through a direct syscall. However, 
+	 * it is not possible to rely on the data being
+	 * effectively written to disk after this method returns.
+	 * To make sure the data is written to disk, destroy 
+	 * this object.
+	 */
     void write (uint8_t *buffer, uint32_t size);
 private:
     SystemFilePrivate *m_priv;
diff --git a/src/core/test.h b/src/core/test.h
index 4bbc66f05..782d6068b 100644
--- a/src/core/test.h
+++ b/src/core/test.h
@@ -33,6 +33,9 @@ namespace ns3 {
 
 class TestManager;
 
+/**
+ * \brief base class for new regressions tests
+ */
 class Test {
 public:
     Test (char const *name);
@@ -44,10 +47,11 @@ protected:
     std::ostream &failure (void);
 };
 
+/**
+ * 
+ */
 class TestManager {
 public:
-    // main methods the test runner is supposed to
-    // invoke.
     static void enableVerbose (void);
     static bool runTests (void);