docs: improve comments on metadata fields and methods

martian/core/metadata.go

@@ -160,17 +160,30 @@ func makeUniquifier() string {
 // metadata for a pipeline node (pipeline, subpipeline, fork, stage, split,
 // chunk, join).
 type Metadata struct {
-	fqname        string
-	path          string
-	finalPath     string
-	contents      map[MetadataFileName]struct{}
-	readCache     map[MetadataFileName]LazyArgumentMap
-	curFilesPath  string
+	fqname string
+
+	path string
+	// This is the human-logical path, e.g. `join`.  This will be the same as
+	// `path` unless the the directory is being uniquified.
+	finalPath string
+	contents  map[MetadataFileName]struct{}
+	readCache map[MetadataFileName]LazyArgumentMap
+	// This is where the stage code writes files.
+	curFilesPath string
+	// This is the "canonical" path to the files, which may be a symlink to
+	// `curFilesPath`.  This will be `finalPath/files` except for the "fake"
+	// `join` metadata of a stage that doesn't split, where it will point up to
+	// the fork's top-level `files`, which will in turn be a symlink to the
+	// singular chunk's `files`.
 	finalFilePath string
 	journalPath   string
 	lastRefresh   time.Time
 	lastHeartbeat time.Time
-	uniquifier    string
+	// An arbitrary string appended to the path that gets changed any time the
+	// stage needs to be restarted, in case the previous attempt didn't actually
+	// terminate properly (perhaps it left orphened subprocesses) so that
+	// the new run doesn't get clobbered by the old one.
+	uniquifier string
 
 	// If non-zero the job was not found last time the job manager was queried,
 	// the chunk will be failed out if the state seems like it's still running
@@ -223,6 +236,7 @@ func newMetadataWithJournalPath(fqname, journalName, p, journalPath string) *Met
 	return self
 }
 
+// glob returns the set of metadata files for the path represented by this object.
 func (self *Metadata) glob(exclude ...MetadataFileName) ([]string, error) {
 	paths, err := util.Readdirnames(self.path)
 	if err != nil {
@@ -264,6 +278,10 @@ func (self *Metadata) symlinks() []string {
 	return symlinks
 }
 
+// enumerateFiles returns the list of items in the files/ directory associated
+// with this metadata object.
+//
+// These are files generated by stage code.
 func (self *Metadata) enumerateFiles() ([]string, error) {
 	paths, err := util.Readdirnames(self.curFilesPath)
 	for i, p := range paths {