From e3168e1d282d6dcac73f710c5deb575613c335b7 Mon Sep 17 00:00:00 2001
From: Evan Martin <martine@danga.com>
Date: Fri, 29 Apr 2011 11:03:03 -0700
Subject: add doxygen-compatibile comments to most classes

---
 src/browse.h      |  6 +++---
 src/build.cc      |  6 ++++--
 src/build.h       | 34 ++++++++++++++++++----------------
 src/build_log.h   | 23 ++++++++++++-----------
 src/build_test.cc |  1 +
 src/eval_env.h    | 10 +++++-----
 src/graph.cc      |  1 +
 src/graph.h       | 12 ++++++++++--
 src/graph_test.cc | 18 ++++++++++++++++++
 src/graphviz.h    |  1 +
 src/ninja.cc      |  2 ++
 src/ninja.h       | 20 ++++++++++++++++----
 src/parsers.h     | 10 +++++++---
 src/subprocess.h  | 16 ++++++++--------
 src/test.h        | 13 +++++++------
 src/util.h        |  6 +++---
 16 files changed, 116 insertions(+), 63 deletions(-)

diff --git a/src/browse.h b/src/browse.h
index f7972c1..d46cbf0 100644
--- a/src/browse.h
+++ b/src/browse.h
@@ -17,9 +17,9 @@
 
 struct State;
 
-// Run in "browse" mode, which execs a Python webserver.
-// |command| is the command used to invoke ninja.
-// This function does not return if it runs successfully.
+/// Run in "browse" mode, which execs a Python webserver.
+/// |command| is the command used to invoke ninja.
+/// This function does not return if it runs successfully.
 void RunBrowsePython(State* state, const char* ninja_command);
 
 #endif  // NINJA_BROWSE_H_
diff --git a/src/build.cc b/src/build.cc
index 98e0bfd..deef7aa 100644
--- a/src/build.cc
+++ b/src/build.cc
@@ -26,11 +26,12 @@
 #include "ninja.h"
 #include "subprocess.h"
 
+/// Tracks the status of a build: completion fraction, printing updates.
 struct BuildStatus {
   BuildStatus();
   void PlanHasTotalEdges(int total);
   void BuildEdgeStarted(Edge* edge);
-  // Returns the time the edge took, in ms.
+  /// Returns the time the edge took, in ms.
   int BuildEdgeFinished(Edge* edge);
 
   void PrintStatus(Edge* edge);
@@ -42,7 +43,7 @@ struct BuildStatus {
   RunningEdgeMap running_edges_;
 
   BuildConfig::Verbosity verbosity_;
-  // Whether we can do fancy terminal control codes.
+  /// Whether we can do fancy terminal control codes.
   bool smart_terminal_;
 };
 
@@ -328,6 +329,7 @@ Edge* RealCommandRunner::NextFinishedCommand(bool* success) {
   return edge;
 }
 
+/// A CommandRunner that doesn't actually run the commands.
 struct DryRunCommandRunner : public CommandRunner {
   virtual ~DryRunCommandRunner() {}
   virtual bool CanRunMore() {
diff --git a/src/build.h b/src/build.h
index cf9398e..b5f53da 100644
--- a/src/build.h
+++ b/src/build.h
@@ -26,31 +26,31 @@ struct DiskInterface;
 struct Node;
 struct State;
 
-// Plan stores the state of a build plan: what we intend to build,
-// which steps we're ready to execute.
+/// Plan stores the state of a build plan: what we intend to build,
+/// which steps we're ready to execute.
 struct Plan {
   Plan();
 
-  // Add a target to our plan (including all its dependencies).
-  // Returns false if we don't need to build this target; may
-  // fill in |err| with an error message if there's a problem.
+  /// Add a target to our plan (including all its dependencies).
+  /// Returns false if we don't need to build this target; may
+  /// fill in |err| with an error message if there's a problem.
   bool AddTarget(Node* node, string* err);
 
   // Pop a ready edge off the queue of edges to build.
   // Returns NULL if there's no work to do.
   Edge* FindWork();
 
-  // Returns true if there's more work to be done.
+  /// Returns true if there's more work to be done.
   bool more_to_do() const { return !want_.empty(); }
 
-  // Dumps the current state of the plan.
+  /// Dumps the current state of the plan.
   void Dump();
 
-  // Mark an edge as done building.  Used internally and by
-  // tests.
+  /// Mark an edge as done building.  Used internally and by
+  /// tests.
   void EdgeFinished(Edge* edge);
 
-  // Number of edges with commands to run.
+  /// Number of edges with commands to run.
   int command_edge_count() const { return command_edges_; }
 
 private:
@@ -61,23 +61,24 @@ private:
   set<Edge*> want_;
   set<Edge*> ready_;
 
-  // Total number of edges that have commands (not phony).
+  /// Total number of edges that have commands (not phony).
   int command_edges_;
 };
 
-// CommandRunner is an interface that wraps running the build
-// subcommands.  This allows tests to abstract out running commands.
-// RealCommandRunner is an implementation that actually runs commands.
+/// CommandRunner is an interface that wraps running the build
+/// subcommands.  This allows tests to abstract out running commands.
+/// RealCommandRunner is an implementation that actually runs commands.
 struct CommandRunner {
   virtual ~CommandRunner() {}
   virtual bool CanRunMore() = 0;
   virtual bool StartCommand(Edge* edge) = 0;
-  // Wait for commands to make progress; return false if there is no
-  // progress to be made.
+  /// Wait for commands to make progress; return false if there is no
+  /// progress to be made.
   virtual bool WaitForCommands() = 0;
   virtual Edge* NextFinishedCommand(bool* success) = 0;
 };
 
+/// Options (e.g. verbosity, parallelism) passed to a build.
 struct BuildConfig {
   BuildConfig() : verbosity(NORMAL), dry_run(false), parallelism(1) {}
 
@@ -91,6 +92,7 @@ struct BuildConfig {
   int parallelism;
 };
 
+/// Builder wraps the build process: starting commands, updating status.
 struct Builder {
   Builder(State* state, const BuildConfig& config);
 
diff --git a/src/build_log.h b/src/build_log.h
index a671467..5d8d6a2 100644
--- a/src/build_log.h
+++ b/src/build_log.h
@@ -22,13 +22,14 @@ using namespace std;
 struct BuildConfig;
 struct Edge;
 
-// Store a log of every command ran for every build.
-// It has a few uses:
-// 1) historical command lines for output files, so we know
-//    when we need to rebuild due to the command changing
-// 2) historical timing information
-// 3) maybe we can generate some sort of build overview output
-//    from it
+/// Store a log of every command ran for every build.
+/// It has a few uses:
+///
+/// 1) historical command lines for output files, so we know
+///    when we need to rebuild due to the command changing
+/// 2) historical timing information
+/// 3) maybe we can generate some sort of build overview output
+///    from it
 struct BuildLog {
   BuildLog();
 
@@ -37,7 +38,7 @@ struct BuildLog {
   void RecordCommand(Edge* edge, int time_ms);
   void Close();
 
-  // Load the on-disk log.
+  /// Load the on-disk log.
   bool Load(const string& path, string* err);
 
   struct LogEntry {
@@ -49,13 +50,13 @@ struct BuildLog {
     }
   };
 
-  // Lookup a previously-run command by its output path.
+  /// Lookup a previously-run command by its output path.
   LogEntry* LookupByOutput(const string& path);
 
-  // Serialize an entry into a log file.
+  /// Serialize an entry into a log file.
   void WriteEntry(FILE* f, const LogEntry& entry);
 
-  // Rewrite the known log entries, throwing away old data.
+  /// Rewrite the known log entries, throwing away old data.
   bool Recompact(const string& path, string* err);
 
   typedef map<string, LogEntry*> Log;
diff --git a/src/build_test.cc b/src/build_test.cc
index 526e5f9..75be860 100644
--- a/src/build_test.cc
+++ b/src/build_test.cc
@@ -17,6 +17,7 @@
 #include "graph.h"
 #include "test.h"
 
+/// Fixture for tests involving Plan.
 // Though Plan doesn't use State, it's useful to have one around
 // to create Nodes and Edges.
 struct PlanTest : public StateTestWithBuiltinRules {
diff --git a/src/eval_env.h b/src/eval_env.h
index f0108ae..b1b63ca 100644
--- a/src/eval_env.h
+++ b/src/eval_env.h
@@ -20,13 +20,13 @@
 #include <vector>
 using namespace std;
 
-// A scope for variable lookups.
+/// An interface for a scope for variable (e.g. "$foo") lookups.
 struct Env {
   virtual string LookupVariable(const string& var) = 0;
 };
 
-// A standard scope, which contains a mapping of variables to values
-// as well as a pointer to a parent scope.
+/// An Env which contains a mapping of variables to values
+/// as well as a pointer to a parent scope.
 struct BindingEnv : public Env {
   BindingEnv() : parent_(NULL) {}
   virtual string LookupVariable(const string& var);
@@ -36,8 +36,8 @@ struct BindingEnv : public Env {
   Env* parent_;
 };
 
-// A tokenized string that contains variable references.
-// Can be evaluated relative to an Env.
+/// A tokenized string that contains variable references.
+/// Can be evaluated relative to an Env.
 struct EvalString {
   bool Parse(const string& input, string* err, size_t* err_index=NULL);
   string Evaluate(Env* env) const;
diff --git a/src/graph.cc b/src/graph.cc
index a4317ba..d953361 100644
--- a/src/graph.cc
+++ b/src/graph.cc
@@ -92,6 +92,7 @@ bool Edge::RecomputeDirty(State* state, DiskInterface* disk_interface,
   return true;
 }
 
+/// An Env for an Edge, providing $in and $out.
 struct EdgeEnv : public Env {
   EdgeEnv(Edge* edge) : edge_(edge) {}
   virtual string LookupVariable(const string& var) {
diff --git a/src/graph.h b/src/graph.h
index f3cfa97..bf714e3 100644
--- a/src/graph.h
+++ b/src/graph.h
@@ -24,13 +24,15 @@ using namespace std;
 struct DiskInterface;
 
 struct Node;
+
+/// Information about a single on-disk file: path, mtime.
 struct FileStat {
   FileStat(const string& path) : path_(path), mtime_(-1), node_(NULL) {}
 
-  // Return true if the file exists (mtime_ got a value).
+  /// Return true if the file exists (mtime_ got a value).
   bool Stat(DiskInterface* disk_interface);
 
-  // Return true if we needed to stat.
+  /// Return true if we needed to stat.
   bool StatIfNecessary(DiskInterface* disk_interface) {
     if (status_known())
       return false;
@@ -56,6 +58,9 @@ struct FileStat {
 };
 
 struct Edge;
+
+/// Information about a node in the dependency graph: the file, whether
+/// it's dirty, etc.
 struct Node {
   Node(FileStat* file) : file_(file), dirty_(false), in_edge_(NULL) {}
 
@@ -67,6 +72,7 @@ struct Node {
   vector<Edge*> out_edges_;
 };
 
+/// An invokable build command and associated metadata (description, etc.).
 struct Rule {
   Rule(const string& name) : name_(name) { }
 
@@ -80,6 +86,8 @@ struct Rule {
 };
 
 struct State;
+
+/// An edge in the dependency graph; links between Nodes using Rules.
 struct Edge {
   Edge() : rule_(NULL), env_(NULL), implicit_deps_(0), order_only_deps_(0) {}
 
diff --git a/src/graph_test.cc b/src/graph_test.cc
index ba41440..56e8ab5 100644
--- a/src/graph_test.cc
+++ b/src/graph_test.cc
@@ -79,3 +79,21 @@ TEST_F(GraphTest, ExplicitImplicit) {
   // the output to be dirty).
   EXPECT_TRUE(GetNode("out.o")->dirty_);
 }
+
+TEST_F(GraphTest, PathWithCurrentDirectory) {
+  ASSERT_NO_FATAL_FAILURE(AssertParse(&state_,
+"rule catdep\n"
+"  depfile = $out.d\n"
+"  command = cat $in > $out\n"
+"build ./out.o: catdep ./foo.cc\n"));
+  fs_.Create("./foo.cc", 1, "");
+  fs_.Create("./out.o.d", 1, "out.o: foo.cc\n");
+  fs_.Create("./out.o", 1, "");
+
+  Edge* edge = GetNode("./out.o")->in_edge_;
+  string err;
+  EXPECT_TRUE(edge->RecomputeDirty(&state_, &fs_, &err));
+  ASSERT_EQ("", err);
+
+  EXPECT_FALSE(GetNode("./out.o")->dirty_);
+}
diff --git a/src/graphviz.h b/src/graphviz.h
index f9b19b6..ab0e2fe 100644
--- a/src/graphviz.h
+++ b/src/graphviz.h
@@ -20,6 +20,7 @@ using namespace std;
 
 struct Node;
 
+/// Runs the process of creating GraphViz .dot file output.
 struct GraphViz {
   void Start();
   void AddTarget(Node* node);
diff --git a/src/ninja.cc b/src/ninja.cc
index c4f78ab..2ed897a 100644
--- a/src/ninja.cc
+++ b/src/ninja.cc
@@ -96,6 +96,8 @@ int GuessParallelism() {
   }
 }
 
+/// An implementation of ManifestParser::FileReader that actually reads
+/// the file.
 struct RealFileReader : public ManifestParser::FileReader {
   bool ReadFile(const string& path, string* content, string* err) {
     return ::ReadFile(path, content, err) == 0;
diff --git a/src/ninja.h b/src/ninja.h
index f387ffc..5311324 100644
--- a/src/ninja.h
+++ b/src/ninja.h
@@ -35,32 +35,44 @@ struct Rule;
 
 int ReadFile(const string& path, string* contents, string* err);
 
+/// Interface for accessing the disk.
+///
+/// Abstract so it can be mocked out for tests.  The real implementation
+/// is RealDiskInterface.
 struct DiskInterface {
-  // stat() a file, returning the mtime, or 0 if missing and -1 on other errors.
+  /// stat() a file, returning the mtime, or 0 if missing and -1 on
+  /// other errors.
   virtual int Stat(const string& path) = 0;
-  // Create a directory, returning false on failure.
+  /// Create a directory, returning false on failure.
   virtual bool MakeDir(const string& path) = 0;
-  // Read a file to a string.  Fill in |err| on error.
+  /// Read a file to a string.  Fill in |err| on error.
   virtual string ReadFile(const string& path, string* err) = 0;
 
-  // Create all the parent directories for path; like mkdir -p `basename path`.
+  /// Create all the parent directories for path; like mkdir -p
+  /// `basename path`.
   bool MakeDirs(const string& path);
 };
 
+/// Implementation of DiskInterface that actually hits the disk.
 struct RealDiskInterface : public DiskInterface {
   virtual int Stat(const string& path);
   virtual bool MakeDir(const string& path);
   virtual string ReadFile(const string& path, string* err);
 };
 
+/// Mapping of path -> FileStat.
 struct StatCache {
   typedef hash_map<string, FileStat*> Paths;
   Paths paths_;
+
   FileStat* GetFile(const string& path);
+
+  /// Dump the mapping to stdout (useful for debugging).
   void Dump();
   void Reload();
 };
 
+/// Global state (file status, loaded rules) for a single run.
 struct State {
   State();
 
diff --git a/src/parsers.h b/src/parsers.h
index 055ba79..31fe8a7 100644
--- a/src/parsers.h
+++ b/src/parsers.h
@@ -23,6 +23,7 @@ using namespace std;
 
 struct BindingEnv;
 
+/// A single parsed token in an input stream.
 struct Token {
   enum Type {
     NONE,
@@ -51,6 +52,7 @@ struct Token {
   const char* end_;
 };
 
+/// Processes an input stream into Tokens.
 struct Tokenizer {
   Tokenizer(bool whitespace_significant)
       : whitespace_significant_(whitespace_significant),
@@ -85,6 +87,7 @@ struct Tokenizer {
   int last_indent_, cur_indent_;
 };
 
+/// Parses simple Makefiles as generated by gcc.
 struct MakefileParser {
   MakefileParser();
   bool Parse(const string& input, string* err);
@@ -96,6 +99,7 @@ struct MakefileParser {
 
 struct State;
 
+/// Parses .ninja files.
 struct ManifestParser {
   struct FileReader {
     virtual bool ReadFile(const string& path, string* content, string* err) = 0;
@@ -107,12 +111,12 @@ struct ManifestParser {
   bool Parse(const string& input, string* err);
 
   bool ParseRule(string* err);
-  // Parse a key=val statement.  If expand is true, evaluate variables
-  // within the value immediately.
+  /// Parse a key=val statement.  If expand is true, evaluate variables
+  /// within the value immediately.
   bool ParseLet(string* key, string* val, bool expand, string* err);
   bool ParseEdge(string* err);
 
-  // Parse either a 'subninja' or 'include' line.
+  /// Parse either a 'subninja' or 'include' line.
   bool ParseFileInclude(Token::Type type, string* err);
 
   State* state_;
diff --git a/src/subprocess.h b/src/subprocess.h
index acdb625..a1edb0d 100644
--- a/src/subprocess.h
+++ b/src/subprocess.h
@@ -20,16 +20,16 @@
 #include <queue>
 using namespace std;
 
-// Subprocess wraps a single async subprocess.  It is entirely
-// passive: it expects the caller to notify it when its fds are ready
-// for reading, as well as call Finish() to reap the child once done()
-// is true.
+/// Subprocess wraps a single async subprocess.  It is entirely
+/// passive: it expects the caller to notify it when its fds are ready
+/// for reading, as well as call Finish() to reap the child once done()
+/// is true.
 struct Subprocess {
   Subprocess();
   ~Subprocess();
   bool Start(const string& command);
   void OnFDReady(int fd);
-  // Returns true on successful process exit.
+  /// Returns true on successful process exit.
   bool Finish();
 
   bool done() const {
@@ -46,9 +46,9 @@ struct Subprocess {
   pid_t pid_;
 };
 
-// SubprocessSet runs a poll() loop around a set of Subprocesses.
-// DoWork() waits for any state change in subprocesses; finished_
-// is a queue of subprocesses as they finish.
+/// SubprocessSet runs a poll() loop around a set of Subprocesses.
+/// DoWork() waits for any state change in subprocesses; finished_
+/// is a queue of subprocesses as they finish.
 struct SubprocessSet {
   void Add(Subprocess* subprocess);
   void DoWork();
diff --git a/src/test.h b/src/test.h
index 988617f..da1ec11 100644
--- a/src/test.h
+++ b/src/test.h
@@ -23,8 +23,8 @@
 
 struct Node;
 
-// A base test fixture that includes a State object with a
-// builtin "cat" rule.
+/// A base test fixture that includes a State object with a
+/// builtin "cat" rule.
 struct StateTestWithBuiltinRules : public testing::Test {
   StateTestWithBuiltinRules();
   Node* GetNode(const string& path);
@@ -34,11 +34,11 @@ struct StateTestWithBuiltinRules : public testing::Test {
 
 void AssertParse(State* state, const char* input);
 
-// An implementation of DiskInterface that uses an in-memory representation
-// of disk state.  It also logs file accesses and directory creations
-// so it can be used by tests to verify disk access patterns.
+/// An implementation of DiskInterface that uses an in-memory representation
+/// of disk state.  It also logs file accesses and directory creations
+/// so it can be used by tests to verify disk access patterns.
 struct VirtualFileSystem : public DiskInterface {
-  // "Create" a file with a given mtime and contents.
+  /// "Create" a file with a given mtime and contents.
   void Create(const string& path, int time, const string& contents);
 
   // DiskInterface
@@ -46,6 +46,7 @@ struct VirtualFileSystem : public DiskInterface {
   virtual bool MakeDir(const string& path);
   virtual string ReadFile(const string& path, string* err);
 
+  /// An entry for a single in-memory file.
   struct Entry {
     int mtime;
     string contents;
diff --git a/src/util.h b/src/util.h
index 3d4d33c..a89cd3d 100644
--- a/src/util.h
+++ b/src/util.h
@@ -19,13 +19,13 @@
 #include <string>
 using namespace std;
 
-// Log a fatal message, dump a backtrace, and exit.
+/// Log a fatal message and exit.
 void Fatal(const char* msg, ...);
 
-// Log an error message.
+/// Log an error message.
 void Error(const char* msg, ...);
 
-// Canonicalize a path like "foo/../bar.h" into just "bar.h".
+/// Canonicalize a path like "foo/../bar.h" into just "bar.h".
 bool CanonicalizePath(string* path, string* err);
 
 #endif  // NINJA_UTIL_H_
-- 
cgit v0.12