Update comments

src/backend/distributed/commands/create_distributed_table.c

@@ -557,6 +557,10 @@ CreateDistributedTable(Oid relationId, Var *distributionColumn, char distributio
 	{
 		if (ClusterHasKnownMetadataWorkers())
 		{
+			/*
+			 * Now that we have created the sequence on the worker we can mark
+			 * it as distributed.
+			 */
 			MarkSequenceListDistributed(dependentSequenceList);
 		}
 	}

src/backend/distributed/metadata/distobject.c

@@ -137,8 +137,13 @@ ObjectExists(const ObjectAddress *address)
 
 
 /*
- * MarkObjectDistributed marks an object as a distributed object by citus. Marking is done
+ * MarkObjectDistributed marks an object as a distributed object by citus.
- * by adding appropriate entries to citus.pg_dist_object.
+ * Marking is done by adding appropriate entries to citus.pg_dist_object.
+ *
+ * This also marks the object as distributed on all of the workers with
+ * metadata (unless localOnly is true). This means that the object should
+ * actually be created on those workers already, otherwise the oid of the
+ * object cannot be looked up.
  */
 void
 MarkObjectDistributed(const ObjectAddress *distAddress, bool localOnly)

src/backend/distributed/metadata/metadata_sync.c

@@ -440,6 +440,15 @@ DropMetadataSnapshotOnNode(WorkerNode *workerNode)
  * (iii) Queries that populate pg_dist_partition table referenced by (ii)
  * (iv)  Queries that populate pg_dist_shard table referenced by (iii)
  * (v)   Queries that populate pg_dist_placement table referenced by (iv)
+ * (vi)  Queries that populate pg_dist_object
+ *
+ * The first argument will be filled with a list of objects that are after the
+ * returned commands have been run. These objects should then be marked
+ * distributed afterwards. This function does not mark them as distributed
+ * directly. The reason for that is marking as distributed is also done on the
+ * metadata workers, and thus can only be done safely once all nodes their
+ * metadata is up to date. Since this function is only called when at least one
+ * node is out of sync, doing it in this function would always fail.
  */
 List *
 MetadataCreateCommands(List **newDistributedObjects)
@@ -818,6 +827,10 @@ NodeListInsertCommand(List *workerNodeList)
 }
 
 
+/*
+ * DistributedObjectCreateCommand generates a command that can be executed to
+ * insert the provided object into pg_dist_object on a worker node.
+ */
 char *
 DistributedObjectCreateCommand(const ObjectAddress *address,
 							   int32 *distributionArgumentIndex,
@@ -891,13 +904,6 @@ DistributedObjectCreateCommand(const ObjectAddress *address,
 }
 
 
-char *
-DistributedObjectDeleteCommand(const ObjectAddress *address)
-{
-	return NULL;
-}
-
-
 /*
  * DistributionCreateCommands generates a commands that can be
  * executed to replicate the metadata for a distributed table.

src/include/distributed/metadata_sync.h

@@ -36,7 +36,6 @@ extern List * MetadataDropCommands(void);
 extern char * DistributedObjectCreateCommand(const ObjectAddress *address,
 											 int32 *distributionArgumentIndex,
 											 int32 *colocationId);
-extern char * DistributedObjectDeleteCommand(const ObjectAddress *address);
 extern char * DistributionCreateCommand(CitusTableCacheEntry *cacheEntry);
 extern char * DistributionDeleteCommand(const char *schemaName,
 										const char *tableName);