Comments for planner.

src/graph/planner/Planner.h

@@ -36,17 +36,28 @@ struct MatchAndInstantiate {
   PlannerInstantiateFunc instantiate;
 };
 
+// A planner generates plans for statements.
+// For example, we have MatchPlanner that generates plan for Match statement.
+// And we have GoPlanner that generates plan for Go statements. Each planner
+// will be registered into the plannersMap in the PlannersRegister when the
+// graphd service starts up.
 class Planner {
  public:
   virtual ~Planner() = default;
 
+  // Each statement might have many planners that match different situations.
+  // Each planner should provide two funtions:
+  // 1. MatchFunc that matchs the proper situation
+  // 2. PlannerInstantiateFunc that instantiates the planner
   static auto& plannersMap() {
     static std::unordered_map<Sentence::Kind, std::vector<MatchAndInstantiate>> plannersMap;
     return plannersMap;
   }
 
+  // Generates plans for each statement based on AsrContext.
   static StatusOr<SubPlan> toPlan(AstContext* astCtx);
 
+  // Transforms the AstContext to a plan which determined by the implementations.
   virtual StatusOr<SubPlan> transform(AstContext* astCtx) = 0;
 
  protected:

src/graph/planner/match/ArgumentFinder.h

@@ -10,6 +10,8 @@
 
 namespace nebula {
 namespace graph {
+// ArgumentFinder finds if a pattern uses a named alias that has already been declared
+// in former patterns.
 class ArgumentFinder final : public StartVidFinder {
  public:
   static std::unique_ptr<ArgumentFinder> make() {

src/graph/planner/match/LabelIndexSeek.h

@@ -11,10 +11,7 @@
 namespace nebula {
 namespace graph {
 
-/*
- * The LabelIndexSeek was designed to find if could get the starting vids by tag
- * index.
- */
+// The LabelIndexSeek finds if a plan could get the starting vids by tag index.
 class LabelIndexSeek final : public StartVidFinder {
  public:
   static std::unique_ptr<LabelIndexSeek> make() {

src/graph/planner/match/MatchClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The MatchClausePlanner was designed to generate plan for match clause;
- */
+// The MatchClausePlanner generates plan for match clause;
 class MatchClausePlanner final : public CypherClausePlanner {
  public:
   MatchClausePlanner() = default;
@@ -62,10 +60,8 @@ class MatchClausePlanner final : public CypherClausePlanner {
                         size_t startIndex,
                         SubPlan& subplan);
 
-  /*
-   * Project all named alias.
-   * TODO: Might not neccessary
-   */
+  // Project all named alias.
+  // TODO: Might not neccessary
   Status projectColumnsBySymbols(MatchClauseContext* matchClauseCtx, SubPlan& plan);
 
   YieldColumn* buildVertexColumn(MatchClauseContext* matchClauseCtx,

src/graph/planner/match/MatchPlanner.h

@@ -11,6 +11,7 @@
 
 namespace nebula {
 namespace graph {
+// MatchPlanner generates plans for Match statement based on AstContext.
 class MatchPlanner final : public Planner {
  public:
   static std::unique_ptr<MatchPlanner> make() {

src/graph/planner/match/OrderByClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The OrderByClausePlanner was designed to generate plan for order by clause;
- */
+// The OrderByClausePlanner generates plan for order by clause;
 class OrderByClausePlanner final : public CypherClausePlanner {
  public:
   OrderByClausePlanner() = default;

src/graph/planner/match/PaginationPlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The PaginationPlanner was designed to generate subplan for skip/limit clause.
- */
+// The PaginationPlanner generates subplan for skip/limit clause.
 class PaginationPlanner final : public CypherClausePlanner {
  public:
   PaginationPlanner() = default;

src/graph/planner/match/PropIndexSeek.h

@@ -10,10 +10,8 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The PropIndexSeek was designed to find if could get starting vids by tag
- * props or edge props index.
- */
+// The PropIndexSeek finds if a plan could get starting vids by tag
+// props or edge props index.
 class PropIndexSeek final : public StartVidFinder {
  public:
   static std::unique_ptr<PropIndexSeek> make() {

src/graph/planner/match/ReturnClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The ReturnClausePlanner was designed to generated plan for return clause.
- */
+// The ReturnClausePlanner generates plan for return clause.
 class ReturnClausePlanner final : public CypherClausePlanner {
  public:
   ReturnClausePlanner() = default;

src/graph/planner/match/ScanSeek.h

@@ -11,10 +11,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The ScanSeek was designed to find if could get the starting vids in
- * filter.
- */
+// The ScanSeek finds if a plan could get the starting vids in filter.
 class ScanSeek final : public StartVidFinder {
  public:
   static std::unique_ptr<ScanSeek> make() {

src/graph/planner/match/SegmentsConnector.h

@@ -13,10 +13,7 @@
 
 namespace nebula {
 namespace graph {
-/**
- * The SegmentsConnector was designed to be a util to help connecting the
- * plan segment.
- */
+// The SegmentsConnector is a util to help connecting the plan segment.
 class SegmentsConnector final {
  public:
   SegmentsConnector() = delete;

src/graph/planner/match/StartVidFinder.h

@@ -15,6 +15,27 @@ class StartVidFinder;
 
 using StartVidFinderInstantiateFunc = std::function<std::unique_ptr<StartVidFinder>()>;
 
+// A StartVidFinder finds a generally good solution for traversing from the vids.
+// Currently we have five StartVidFinders:
+// 1. VertexIdSeek find if a plan could traverse from a given vid.
+// MATCH(n) WHERE id(n) = value RETURN n
+//
+// 2. ArgumentFinder finds if a plan could traverse from some vids that already
+// beed traversed.
+// MATCH (n)-[]-(l), (l)-[]-(m) return n,l,m
+// MATCH (n)-[]-(l) MATCH (l)-[]-(m) return n,l,m
+//
+// 3. PropIndexSeek finds if a plan could traverse from some vids that could be
+// read from the property indices.
+// MATCH(n:Tag{prop:value}) RETURN n
+// MATCH(n:Tag) WHERE n.prop = value RETURN n
+//
+// 4. LabelIndexSeek finds if a plan could traverse from some vids that could be
+// read from the label indices.
+// MATCH(n: tag) RETURN n
+// MATCH(s)-[:edge]->(e) RETURN e
+//
+// 5. ScanSeek finds if a plan could traverse from some vids by scanning.
 class StartVidFinder {
  public:
   virtual ~StartVidFinder() = default;
@@ -26,8 +47,12 @@ class StartVidFinder {
 
   bool match(PatternContext* patternCtx);
 
+  // The derived class should implement matchNode if the finder has
+  // the ability to find vids from node pattern.
   virtual bool matchNode(NodeContext* nodeCtx) = 0;
 
+  // The derived class should implement matchEdge if the finder has
+  // the ability to find vids from edge pattern.
   virtual bool matchEdge(EdgeContext* nodeCtx) = 0;
 
   StatusOr<SubPlan> transform(PatternContext* patternCtx);

src/graph/planner/match/UnwindClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The UnwindClausePlanner was designed to generate plan for unwind clause
- */
+// The UnwindClausePlanner generates plan for unwind clause
 class UnwindClausePlanner final : public CypherClausePlanner {
  public:
   UnwindClausePlanner() = default;

src/graph/planner/match/VertexIdSeek.h

@@ -11,10 +11,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The VertexIdSeek was designed to find if could get the starting vids in
- * filter.
- */
+// The VertexIdSeek find if a plan could get the starting vids in filters.
 class VertexIdSeek final : public StartVidFinder {
  public:
   static std::unique_ptr<VertexIdSeek> make() {

src/graph/planner/match/WhereClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The WhereClausePlanner was designed to generate plan for where clause.
- */
+// The WhereClausePlanner generates plan for where clause.
 class WhereClausePlanner final : public CypherClausePlanner {
  public:
   explicit WhereClausePlanner(bool needStableFilter = false)

src/graph/planner/match/WithClausePlanner.h

@@ -10,9 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The WithClausePlanner was designed to generate plan for with clause.
- */
+// The WithClausePlanner generates plan for with clause.
 class WithClausePlanner final : public CypherClausePlanner {
  public:
   WithClausePlanner() = default;

src/graph/planner/match/YieldClausePlanner.h

@@ -10,10 +10,7 @@
 
 namespace nebula {
 namespace graph {
-/*
- * The YieldClausePlanner was designed to generate plan for yield clause in
- * cypher
- */
+// The YieldClausePlanner generates plan for yield clause
 class YieldClausePlanner final : public CypherClausePlanner {
  public:
   YieldClausePlanner() = default;

src/graph/planner/ngql/GoPlanner.cpp

@@ -90,11 +90,8 @@ Expression* GoPlanner::loopCondition(uint32_t steps, const std::string& var) {
   return LogicalExpression::makeAnd(pool, step, earlyEnd);
 }
 
-/*
- * extract vid and edge's prop from GN
- * for joinDst & joinInput
- * output colNames {srcProps, edgeProps, kVid, "JOIN_DST_VID"}
- */
+// Extracts vid and edge's prop from GN for joinDst & joinInput.
+// The root plan node will output colNames of {srcProps, edgeProps, kVid, "JOIN_DST_VID"}.
 PlanNode* GoPlanner::extractSrcEdgePropsFromGN(PlanNode* dep, const std::string& input) {
   auto& srcEdgePropsExpr = goCtx_->srcEdgePropsExpr;
   auto* pool = goCtx_->qctx->objPool();
@@ -116,11 +113,8 @@ PlanNode* GoPlanner::extractSrcEdgePropsFromGN(PlanNode* dep, const std::string&
   return project;
 }
 
-/*
- * extract vid and dst from GN
- * for trackStartVid
- * output ColNames {srcVidColName, "TRACK_DST_VID"}
- */
+// Extracts vid and dst from GN for trackStartVid.
+// The root plan node will output ColNames of {srcVidColName, "TRACK_DST_VID"}.
 PlanNode* GoPlanner::extractSrcDstFromGN(PlanNode* dep, const std::string& input) {
   auto qctx = goCtx_->qctx;
   auto* pool = qctx->objPool();
@@ -138,11 +132,8 @@ PlanNode* GoPlanner::extractSrcDstFromGN(PlanNode* dep, const std::string& input
   return dedup;
 }
 
-/*
- * extract vid from runTime input
- * for joinInput
- * output ColNames {runtimeVidName, dstVidColName}
- */
+// Extracts vid from runTime input for joinInput.
+// The root plan node will output ColNames of {runtimeVidName, dstVidColName}.
 PlanNode* GoPlanner::extractVidFromRuntimeInput(PlanNode* dep) {
   if (dep == nullptr) {
     return dep;
@@ -166,13 +157,11 @@ PlanNode* GoPlanner::extractVidFromRuntimeInput(PlanNode* dep) {
   return dedup;
 }
 
-/*
- * establish a mapping between the original vId and the expanded destination vId
- * during each step of the expansion in the n-step and mton-step scenario
- * left: n-1 steps
- * right: step n
- * output ColNames {runtimeVidName, dstVidColName}
- */
+// Establishes a mapping between the original vId and the expanded destination vId
+// during each step of the expansion in the n-step and mton-step scenario.
+// The root plan node will output ColNames of {runtimeVidName, dstVidColName}.
+// left: (n-1)th step
+// right: (n)th step
 PlanNode* GoPlanner::trackStartVid(PlanNode* left, PlanNode* right) {
   auto qctx = goCtx_->qctx;
   auto* pool = qctx->objPool();
@@ -207,10 +196,8 @@ PlanNode* GoPlanner::trackStartVid(PlanNode* left, PlanNode* right) {
   return dedup;
 }
 
-/*
- * output ColNames {srcProps, edgeProps, kVid, "JOIN_DST_VID", "DST_VID",
- * dstProps}
- */
+// The root plan node will output ColNames of
+// {srcProps, edgeProps, kVid, "JOIN_DST_VID", "DST_VID", dstProps}
 PlanNode* GoPlanner::buildJoinDstPlan(PlanNode* dep) {
   auto qctx = goCtx_->qctx;
   auto* pool = qctx->objPool();
@@ -279,11 +266,10 @@ PlanNode* GoPlanner::buildJoinInputPlan(PlanNode* dep) {
   return join;
 }
 
-/*
- * left's colName dstVidColName join right's colName kVid
- * left  : n-1 steps
- * right : last step
- */
+// The column named as dstVidColName of the left plan node join on the column named as kVid of the
+// right one.
+// left  : (n-1)th step
+// right : last step
 PlanNode* GoPlanner::lastStepJoinInput(PlanNode* left, PlanNode* right) {
   auto qctx = goCtx_->qctx;
   auto* pool = qctx->objPool();
@@ -374,8 +360,7 @@ PlanNode* GoPlanner::buildSampleLimitImpl(PlanNode* input, T sampleLimit) {
   return node;
 }
 
-// generate
-// $limits[$step-1]
+// Generates $limits[$step-1]
 Expression* GoPlanner::stepSampleLimit() {
   auto qctx = goCtx_->qctx;
   // $limits