Pass through golint warnings

.travis.yml

@@ -28,23 +28,23 @@ before_install:
   - sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-6 90
   - wget -O protoc.zip https://github.com/google/protobuf/releases/download/v3.5.0/protoc-3.5.0-linux-x86_64.zip
   - unzip -d ~/.local protoc.zip && rm protoc.zip
+  - go get -v github.com/golang/lint/golint
   - go get -v github.com/gogo/protobuf/protoc-gen-gogo
-  - wget http://mirrors.kernel.org/ubuntu/pool/main/m/make-dfsg/make_4.1-9.1_amd64.deb
-  - dpkg -x make_4.1-9.1_amd64.deb ~ && rm make_4.1-9.1_amd64.deb
+  - git clone --depth 1 https://github.com/src-d/go-git $GOPATH/src/gopkg.in/src-d/go-git.v4
   - wget https://bootstrap.pypa.io/get-pip.py && python3 get-pip.py --user && rm get-pip.py
+  - docker run -d --privileged -p 9432:9432 --name bblfshd bblfsh/bblfshd
+  - docker exec -it bblfshd bblfshctl driver install --all
   - export PATH=~/.local/bin:~/usr/bin:$PATH
   - make --version
   - pip3 --version
+  - pip3 install --user -r requirements.txt tensorflow
 
 install:
-  - git clone --depth 1 https://github.com/src-d/go-git $GOPATH/src/gopkg.in/src-d/go-git.v4
   - make
-  - pip3 install --user -r requirements.txt tensorflow
-  - docker run -d --privileged -p 9432:9432 --name bblfshd bblfsh/bblfshd
-  - docker exec -it bblfshd bblfshctl driver install --all
   
 script:
   - go vet ./...
+  - golint ./...
   - go test -v -cpu=1,2 -coverprofile=coverage.txt -covermode=count gopkg.in/src-d/hercules.v3
   - $GOPATH/bin/hercules version
   - $GOPATH/bin/hercules --burndown --couples --quiet --pb https://github.com/src-d/hercules > 1.pb

blob_cache.go

@@ -33,20 +33,28 @@ const (
 	DependencyBlobCache = "blob_cache"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (blobCache *BlobCache) Name() string {
 	return "BlobCache"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (blobCache *BlobCache) Provides() []string {
 	arr := [...]string{DependencyBlobCache}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (blobCache *BlobCache) Requires() []string {
 	arr := [...]string{DependencyTreeChanges}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (blobCache *BlobCache) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name: ConfigBlobCacheIgnoreMissingSubmodules,
@@ -59,17 +67,25 @@ func (blobCache *BlobCache) ListConfigurationOptions() []ConfigurationOption {
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (blobCache *BlobCache) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigBlobCacheIgnoreMissingSubmodules].(bool); exists {
 		blobCache.IgnoreMissingSubmodules = val
 	}
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (blobCache *BlobCache) Initialize(repository *git.Repository) {
 	blobCache.repository = repository
 	blobCache.cache = map[plumbing.Hash]*object.Blob{}
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (blobCache *BlobCache) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit)
 	changes := deps[DependencyTreeChanges].(object.Changes)

burndown.go

@@ -119,20 +119,28 @@ const (
 	authorSelf = (1 << 18) - 2
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (analyser *BurndownAnalysis) Name() string {
 	return "Burndown"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (analyser *BurndownAnalysis) Provides() []string {
 	return []string{}
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (analyser *BurndownAnalysis) Requires() []string {
 	arr := [...]string{
 		DependencyFileDiff, DependencyTreeChanges, DependencyBlobCache, DependencyDay, DependencyAuthor}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (analyser *BurndownAnalysis) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigBurndownGranularity,
@@ -164,6 +172,7 @@ func (analyser *BurndownAnalysis) ListConfigurationOptions() []ConfigurationOpti
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (analyser *BurndownAnalysis) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigBurndownGranularity].(int); exists {
 		analyser.Granularity = val
@@ -187,10 +196,13 @@ func (analyser *BurndownAnalysis) Configure(facts map[string]interface{}) {
 	}
 }
 
+// Flag for the command line switch which enables this analysis.
 func (analyser *BurndownAnalysis) Flag() string {
 	return "burndown"
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (analyser *BurndownAnalysis) Initialize(repository *git.Repository) {
 	if analyser.Granularity <= 0 {
 		fmt.Fprintf(os.Stderr, "Warning: adjusted the granularity to %d days\n",
@@ -219,6 +231,11 @@ func (analyser *BurndownAnalysis) Initialize(repository *git.Repository) {
 	analyser.previousDay = 0
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (analyser *BurndownAnalysis) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	sampling := analyser.Sampling
 	if sampling == 0 {
@@ -253,7 +270,7 @@ func (analyser *BurndownAnalysis) Consume(deps map[string]interface{}) (map[stri
 	return nil, nil
 }
 
-// Finalize() returns BurndownResult.
+// Finalize returns the result of the analysis. Further Consume() calls are not expected.
 func (analyser *BurndownAnalysis) Finalize() interface{} {
 	gs, fss, pss := analyser.groupStatus()
 	analyser.updateHistories(gs, fss, pss, 1)
@@ -291,6 +308,8 @@ func (analyser *BurndownAnalysis) Finalize() interface{} {
 	}
 }
 
+// Serialize converts the analysis result as returned by Finalize() to text or bytes.
+// The text format is YAML and the bytes format is Protocol Buffers.
 func (analyser *BurndownAnalysis) Serialize(result interface{}, binary bool, writer io.Writer) error {
 	burndownResult := result.(BurndownResult)
 	if binary {
@@ -300,6 +319,7 @@ func (analyser *BurndownAnalysis) Serialize(result interface{}, binary bool, wri
 	return nil
 }
 
+// Deserialize converts the specified protobuf bytes to BurndownResult.
 func (analyser *BurndownAnalysis) Deserialize(pbmessage []byte) (interface{}, error) {
 	msg := pb.BurndownAnalysisResults{}
 	err := proto.Unmarshal(pbmessage, &msg)
@@ -342,6 +362,7 @@ func (analyser *BurndownAnalysis) Deserialize(pbmessage []byte) (interface{}, er
 	return result, nil
 }
 
+// MergeResults combines two BurndownResult-s together.
 func (analyser *BurndownAnalysis) MergeResults(
 	r1, r2 interface{}, c1, c2 *CommonAnalysisResult) interface{} {
 	bar1 := r1.(BurndownResult)

cmd/hercules/root.go

@@ -203,7 +203,7 @@ targets can be added using the --plugin system.`,
 		}
 		if !disableStatus {
 			bar.Finish()
-			fmt.Fprint(os.Stderr, "\r" + strings.Repeat(" ", 80) + "\r")
+			fmt.Fprint(os.Stderr, "\r"+strings.Repeat(" ", 80)+"\r")
 			if !terminal.IsTerminal(int(os.Stdout.Fd())) {
 				fmt.Fprint(os.Stderr, "writing...\r")
 			}

couples.go

@@ -42,23 +42,32 @@ type CouplesResult struct {
 	reversedPeopleDict []string
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (couples *CouplesAnalysis) Name() string {
 	return "Couples"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (couples *CouplesAnalysis) Provides() []string {
 	return []string{}
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (couples *CouplesAnalysis) Requires() []string {
 	arr := [...]string{DependencyAuthor, DependencyTreeChanges}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (couples *CouplesAnalysis) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (couples *CouplesAnalysis) Configure(facts map[string]interface{}) {
 	if val, exists := facts[FactIdentityDetectorPeopleCount].(int); exists {
 		couples.PeopleNumber = val
@@ -66,10 +75,13 @@ func (couples *CouplesAnalysis) Configure(facts map[string]interface{}) {
 	}
 }
 
+// Flag for the command line switch which enables this analysis.
 func (couples *CouplesAnalysis) Flag() string {
 	return "couples"
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (couples *CouplesAnalysis) Initialize(repository *git.Repository) {
 	couples.people = make([]map[string]int, couples.PeopleNumber+1)
 	for i := range couples.people {
@@ -79,6 +91,11 @@ func (couples *CouplesAnalysis) Initialize(repository *git.Repository) {
 	couples.files = map[string]map[string]int{}
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (couples *CouplesAnalysis) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	author := deps[DependencyAuthor].(int)
 	if author == AuthorMissing {
@@ -144,6 +161,7 @@ func (couples *CouplesAnalysis) Consume(deps map[string]interface{}) (map[string
 	return nil, nil
 }
 
+// Finalize returns the result of the analysis. Further Consume() calls are not expected.
 func (couples *CouplesAnalysis) Finalize() interface{} {
 	filesSequence := make([]string, len(couples.files))
 	i := 0
@@ -196,6 +214,8 @@ func (couples *CouplesAnalysis) Finalize() interface{} {
 	}
 }
 
+// Serialize converts the analysis result as returned by Finalize() to text or bytes.
+// The text format is YAML and the bytes format is Protocol Buffers.
 func (couples *CouplesAnalysis) Serialize(result interface{}, binary bool, writer io.Writer) error {
 	couplesResult := result.(CouplesResult)
 	if binary {
@@ -205,6 +225,7 @@ func (couples *CouplesAnalysis) Serialize(result interface{}, binary bool, write
 	return nil
 }
 
+// Deserialize converts the specified protobuf bytes to CouplesResult.
 func (couples *CouplesAnalysis) Deserialize(pbmessage []byte) (interface{}, error) {
 	message := pb.CouplesAnalysisResults{}
 	err := proto.Unmarshal(pbmessage, &message)
@@ -240,6 +261,7 @@ func (couples *CouplesAnalysis) Deserialize(pbmessage []byte) (interface{}, erro
 	return result, nil
 }
 
+// MergeResults combines two CouplesAnalysis-s together.
 func (couples *CouplesAnalysis) MergeResults(r1, r2 interface{}, c1, c2 *CommonAnalysisResult) interface{} {
 	cr1 := r1.(CouplesResult)
 	cr2 := r2.(CouplesResult)

day.go

@@ -20,30 +20,46 @@ const (
 	DependencyDay = "day"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (days *DaysSinceStart) Name() string {
 	return "DaysSinceStart"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (days *DaysSinceStart) Provides() []string {
 	arr := [...]string{DependencyDay}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (days *DaysSinceStart) Requires() []string {
 	return []string{}
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (days *DaysSinceStart) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (days *DaysSinceStart) Configure(facts map[string]interface{}) {}
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (days *DaysSinceStart) Initialize(repository *git.Repository) {
 	days.day0 = time.Time{}
 	days.previousDay = 0
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (days *DaysSinceStart) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit)
 	index := deps["index"].(int)

diff.go

@@ -36,20 +36,28 @@ type FileDiffData struct {
 	Diffs          []diffmatchpatch.Diff
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (diff *FileDiff) Name() string {
 	return "FileDiff"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (diff *FileDiff) Provides() []string {
 	arr := [...]string{DependencyFileDiff}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (diff *FileDiff) Requires() []string {
 	arr := [...]string{DependencyTreeChanges, DependencyBlobCache}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (diff *FileDiff) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigFileDiffDisableCleanup,
@@ -61,14 +69,22 @@ func (diff *FileDiff) ListConfigurationOptions() []ConfigurationOption {
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (diff *FileDiff) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigFileDiffDisableCleanup].(bool); exists {
 		diff.CleanupDisabled = val
 	}
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (diff *FileDiff) Initialize(repository *git.Repository) {}
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (diff *FileDiff) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	result := map[string]FileDiffData{}
 	cache := deps[DependencyBlobCache].(map[plumbing.Hash]*object.Blob)

diff_refiner.go

@@ -15,34 +15,51 @@ import (
 type FileDiffRefiner struct {
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (ref *FileDiffRefiner) Name() string {
 	return "FileDiffRefiner"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (ref *FileDiffRefiner) Provides() []string {
 	arr := [...]string{DependencyFileDiff}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (ref *FileDiffRefiner) Requires() []string {
 	arr := [...]string{DependencyFileDiff, DependencyUastChanges}
 	return arr[:]
 }
 
+// Features which must be enabled for this PipelineItem to be automatically inserted into the DAG.
 func (ref *FileDiffRefiner) Features() []string {
 	arr := [...]string{FeatureUast}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (ref *FileDiffRefiner) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (ref *FileDiffRefiner) Configure(facts map[string]interface{}) {}
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (ref *FileDiffRefiner) Initialize(repository *git.Repository) {
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (ref *FileDiffRefiner) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	changesList := deps[DependencyUastChanges].([]UASTChange)
 	changes := map[string]UASTChange{}

file.go

@@ -259,6 +259,7 @@ func (file *File) Update(time int, pos int, insLength int, delLength int) {
 	}
 }
 
+// Status returns the bound status object by the specified index.
 func (file *File) Status(index int) interface{} {
 	if index < 0 || index >= len(file.statuses) {
 		panic(fmt.Sprintf("status index %d is out of bounds [0, %d)",

file_history.go

@@ -25,36 +25,51 @@ type FileHistoryResult struct {
 	Files map[string][]plumbing.Hash
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (history *FileHistory) Name() string {
 	return "FileHistory"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (history *FileHistory) Provides() []string {
 	return []string{}
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (history *FileHistory) Requires() []string {
 	arr := [...]string{DependencyTreeChanges}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (history *FileHistory) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Flag for the command line switch which enables this analysis.
 func (history *FileHistory) Flag() string {
 	return "file-history"
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (history *FileHistory) Configure(facts map[string]interface{}) {
 }
 
-// Initialize resets the internal temporary data structures and prepares the object for Consume().
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (history *FileHistory) Initialize(repository *git.Repository) {
 	history.files = map[string][]plumbing.Hash{}
 }
 
-// Consume is called for every commit in the sequence.
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (history *FileHistory) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit).Hash
 	changes := deps[DependencyTreeChanges].(object.Changes)
@@ -79,11 +94,13 @@ func (history *FileHistory) Consume(deps map[string]interface{}) (map[string]int
 	return nil, nil
 }
 
+// Finalize returns the result of the analysis. Further Consume() calls are not expected.
 func (history *FileHistory) Finalize() interface{} {
 	return FileHistoryResult{Files: history.files}
 }
 
-// Serialize converts the result from Finalize() to either Protocol Buffers or YAML.
+// Serialize converts the analysis result as returned by Finalize() to text or bytes.
+// The text format is YAML and the bytes format is Protocol Buffers.
 func (history *FileHistory) Serialize(result interface{}, binary bool, writer io.Writer) error {
 	historyResult := result.(FileHistoryResult)
 	if binary {

identity.go

@@ -47,19 +47,27 @@ const (
 	DependencyAuthor = "author"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (id *IdentityDetector) Name() string {
 	return "IdentityDetector"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (id *IdentityDetector) Provides() []string {
 	arr := [...]string{DependencyAuthor}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (id *IdentityDetector) Requires() []string {
 	return []string{}
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (id *IdentityDetector) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigIdentityDetectorPeopleDictPath,
@@ -71,6 +79,7 @@ func (id *IdentityDetector) ListConfigurationOptions() []ConfigurationOption {
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (id *IdentityDetector) Configure(facts map[string]interface{}) {
 	if val, exists := facts[FactIdentityDetectorPeopleDict].(map[string]int); exists {
 		id.PeopleDict = val
@@ -97,9 +106,16 @@ func (id *IdentityDetector) Configure(facts map[string]interface{}) {
 	facts[FactIdentityDetectorReversedPeopleDict] = id.ReversedPeopleDict
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (id *IdentityDetector) Initialize(repository *git.Repository) {
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (id *IdentityDetector) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit)
 	signature := commit.Author
@@ -113,6 +129,9 @@ func (id *IdentityDetector) Consume(deps map[string]interface{}) (map[string]int
 	return map[string]interface{}{DependencyAuthor: authorID}, nil
 }
 
+// LoadPeopleDict loads author signatures from a text file.
+// The format is one signature per line, and the signature consists of several
+// keys separated by "|". The first key is the main one and used to reference all the rest.
 func (id *IdentityDetector) LoadPeopleDict(path string) error {
 	file, err := os.Open(path)
 	if err != nil {
@@ -137,6 +156,7 @@ func (id *IdentityDetector) LoadPeopleDict(path string) error {
 	return nil
 }
 
+// GeneratePeopleDict loads author signatures from the specified list of Git commits.
 func (id *IdentityDetector) GeneratePeopleDict(commits []*object.Commit) {
 	dict := map[string]int{}
 	emails := map[int][]string{}

pipeline.go

@@ -58,7 +58,7 @@ type ConfigurationOption struct {
 	Default interface{}
 }
 
-// FormatDefault() converts the default value of ConfigurationOption to string.
+// FormatDefault converts the default value of ConfigurationOption to string.
 // Used in the command line interface to show the argument's default value.
 func (opt ConfigurationOption) FormatDefault() string {
 	if opt.Type != StringConfigurationOption {
@@ -131,17 +131,17 @@ type CommonAnalysisResult struct {
 	RunTime time.Duration
 }
 
-// BeginTimeAsTime() converts the UNIX timestamp of the beginning to Go time.
+// BeginTimeAsTime converts the UNIX timestamp of the beginning to Go time.
 func (car *CommonAnalysisResult) BeginTimeAsTime() time.Time {
 	return time.Unix(car.BeginTime, 0)
 }
 
-// EndTimeAsTime() converts the UNIX timestamp of the ending to Go time.
+// EndTimeAsTime converts the UNIX timestamp of the ending to Go time.
 func (car *CommonAnalysisResult) EndTimeAsTime() time.Time {
 	return time.Unix(car.EndTime, 0)
 }
 
-// Merge() combines the CommonAnalysisResult with an other one.
+// Merge combines the CommonAnalysisResult with an other one.
 // We choose the earlier BeginTime, the later EndTime, sum the number of commits and the
 // elapsed run times.
 func (car *CommonAnalysisResult) Merge(other *CommonAnalysisResult) {
@@ -158,7 +158,7 @@ func (car *CommonAnalysisResult) Merge(other *CommonAnalysisResult) {
 	car.RunTime += other.RunTime
 }
 
-// FillMetadata() copies the data to a Protobuf message.
+// FillMetadata copies the data to a Protobuf message.
 func (car *CommonAnalysisResult) FillMetadata(meta *pb.Metadata) *pb.Metadata {
 	meta.BeginUnixTime = car.BeginTime
 	meta.EndUnixTime = car.EndTime
@@ -223,23 +223,32 @@ func NewPipeline(repository *git.Repository) *Pipeline {
 	}
 }
 
+// GetFact returns the value of the fact with the specified name.
 func (pipeline *Pipeline) GetFact(name string) interface{} {
 	return pipeline.facts[name]
 }
 
+// SetFact sets the value of the fact with the specified name.
 func (pipeline *Pipeline) SetFact(name string, value interface{}) {
 	pipeline.facts[name] = value
 }
 
+// GetFeature returns the state of the feature with the specified name (enabled/disabled) and
+// whether it exists. See also: FeaturedPipelineItem.
 func (pipeline *Pipeline) GetFeature(name string) (bool, bool) {
 	val, exists := pipeline.features[name]
 	return val, exists
 }
 
+// SetFeature sets the value of the feature with the specified name.
+// See also: FeaturedPipelineItem.
 func (pipeline *Pipeline) SetFeature(name string) {
 	pipeline.features[name] = true
 }
 
+// SetFeaturesFromFlags enables the features which were specified through the command line flags
+// which belong to the given PipelineItemRegistry instance.
+// See also: AddItem().
 func (pipeline *Pipeline) SetFeaturesFromFlags(registry ...*PipelineItemRegistry) {
 	var ffr *PipelineItemRegistry
 	if len(registry) == 0 {
@@ -254,6 +263,8 @@ func (pipeline *Pipeline) SetFeaturesFromFlags(registry ...*PipelineItemRegistry
 	}
 }
 
+// DeployItem inserts a PipelineItem into the pipeline. It also recursively creates all of it's
+// dependencies (PipelineItem.Requires()). Returns the same item as specified in the arguments.
 func (pipeline *Pipeline) DeployItem(item PipelineItem) PipelineItem {
 	fpi, ok := item.(FeaturedPipelineItem)
 	if ok {
@@ -298,11 +309,14 @@ func (pipeline *Pipeline) DeployItem(item PipelineItem) PipelineItem {
 	return item
 }
 
+// AddItem inserts a PipelineItem into the pipeline. It does not check any dependencies.
+// See also: DeployItem().
 func (pipeline *Pipeline) AddItem(item PipelineItem) PipelineItem {
 	pipeline.items = append(pipeline.items, item)
 	return item
 }
 
+// RemoveItem deletes a PipelineItem from the pipeline. It leaves all the rest of the items intact.
 func (pipeline *Pipeline) RemoveItem(item PipelineItem) {
 	for i, reg := range pipeline.items {
 		if reg == item {
@@ -312,6 +326,7 @@ func (pipeline *Pipeline) RemoveItem(item PipelineItem) {
 	}
 }
 
+// Len returns the number of items in the pipeline.
 func (pipeline *Pipeline) Len() int {
 	return len(pipeline.items)
 }
@@ -417,6 +432,7 @@ func (pipeline *Pipeline) resolve(dumpPath string) {
 			}
 		}
 	}
+	// Try to break the cycles in some known scenarios.
 	if len(ambiguousMap) > 0 {
 		ambiguous := []string{}
 		for key := range ambiguousMap {
@@ -482,6 +498,9 @@ func (pipeline *Pipeline) resolve(dumpPath string) {
 	}
 }
 
+// Initialize prepares the pipeline for the execution (Run()). This function
+// resolves the execution DAG, Configure()-s and Initialize()-s the items in it in the
+// topological dependency order. `facts` are passed inside Configure(). They are mutable.
 func (pipeline *Pipeline) Initialize(facts map[string]interface{}) {
 	if facts == nil {
 		facts = map[string]interface{}{}

rbtree/rbtree.go

@@ -29,12 +29,12 @@ type RBTree struct {
 	count int
 }
 
-// Return the number of elements in the tree.
+// Len returns the number of elements in the tree.
 func (root *RBTree) Len() int {
 	return root.count
 }
 
-// A convenience function for finding an element equal to Key. Return
+// Get is a convenience function for finding an element equal to Key. Returns
 // nil if not found.
 func (root *RBTree) Get(key int) *int {
 	n, exact := root.findGE(key)
@@ -44,15 +44,15 @@ func (root *RBTree) Get(key int) *int {
 	return nil
 }
 
-// Create an iterator that points to the minimum item in the tree
-// If the tree is empty, return Limit()
+// Min creates an iterator that points to the minimum item in the tree.
+// If the tree is empty, returns Limit()
 func (root *RBTree) Min() Iterator {
 	return Iterator{root, root.minNode}
 }
 
-// Create an iterator that points at the maximum item in the tree
+// Max creates an iterator that points at the maximum item in the tree.
 //
-// If the tree is empty, return NegativeLimit()
+// If the tree is empty, returns NegativeLimit().
 func (root *RBTree) Max() Iterator {
 	if root.maxNode == nil {
 		return Iterator{root, negativeLimitNode}
@@ -60,27 +60,27 @@ func (root *RBTree) Max() Iterator {
 	return Iterator{root, root.maxNode}
 }
 
-// Create an iterator that points beyond the maximum item in the tree
+// Limit creates an iterator that points beyond the maximum item in the tree.
 func (root *RBTree) Limit() Iterator {
 	return Iterator{root, nil}
 }
 
-// Create an iterator that points before the minimum item in the tree
+// NegativeLimit creates an iterator that points before the minimum item in the tree.
 func (root *RBTree) NegativeLimit() Iterator {
 	return Iterator{root, negativeLimitNode}
 }
 
-// Find the smallest element N such that N >= Key, and return the
+// FindGE finds the smallest element N such that N >= Key, and returns the
 // iterator pointing to the element. If no such element is found,
-// return root.Limit().
+// returns root.Limit().
 func (root *RBTree) FindGE(key int) Iterator {
 	n, _ := root.findGE(key)
 	return Iterator{root, n}
 }
 
-// Find the largest element N such that N <= Key, and return the
+// FindLE finds the largest element N such that N <= Key, and returns the
 // iterator pointing to the element. If no such element is found,
-// return iter.NegativeLimit().
+// returns iter.NegativeLimit().
 func (root *RBTree) FindLE(key int) Iterator {
 	n, exact := root.findGE(key)
 	if exact {
@@ -162,7 +162,7 @@ func (root *RBTree) Insert(item Item) (bool, Iterator) {
 	return true, Iterator{root, insN}
 }
 
-// Delete an item with the given Key. Return true iff the item was
+// DeleteWithKey deletes an item with the given Key. Returns true iff the item was
 // found.
 func (root *RBTree) DeleteWithKey(key int) bool {
 	iter := root.FindGE(key)
@@ -173,7 +173,7 @@ func (root *RBTree) DeleteWithKey(key int) bool {
 	return false
 }
 
-// Delete the current item.
+// DeleteWithIterator deletes the current item.
 //
 // REQUIRES: !iter.Limit() && !iter.NegativeLimit()
 func (root *RBTree) DeleteWithIterator(iter Iterator) {
@@ -192,39 +192,40 @@ type Iterator struct {
 	node *node
 }
 
+// Equal checks for the underlying nodes equality.
 func (iter Iterator) Equal(other Iterator) bool {
 	return iter.node == other.node
 }
 
-// Check if the iterator points beyond the max element in the tree
+// Limit checks if the iterator points beyond the max element in the tree.
 func (iter Iterator) Limit() bool {
 	return iter.node == nil
 }
 
-// Check if the iterator points to the minimum element in the tree
+// Min checks if the iterator points to the minimum element in the tree.
 func (iter Iterator) Min() bool {
 	return iter.node == iter.root.minNode
 }
 
-// Check if the iterator points to the maximum element in the tree
+// Max checks if the iterator points to the maximum element in the tree.
 func (iter Iterator) Max() bool {
 	return iter.node == iter.root.maxNode
 }
 
-// Check if the iterator points before the minimum element in the tree
+// NegativeLimit checks if the iterator points before the minimum element in the tree.
 func (iter Iterator) NegativeLimit() bool {
 	return iter.node == negativeLimitNode
 }
 
-// Return the current element. Allows mutating the node
-// (Key to be changed with care!).
+// Item returns the current element. Allows mutating the node
+// (key to be changed with care!).
 //
 // REQUIRES: !iter.Limit() && !iter.NegativeLimit()
 func (iter Iterator) Item() *Item {
 	return &iter.node.item
 }
 
-// Create a new iterator that points to the successor of the current element.
+// Next creates a new iterator that points to the successor of the current element.
 //
 // REQUIRES: !iter.Limit()
 func (iter Iterator) Next() Iterator {
@@ -235,7 +236,7 @@ func (iter Iterator) Next() Iterator {
 	return Iterator{iter.root, iter.node.doNext()}
 }
 
-// Create a new iterator that points to the predecessor of the current
+// Prev creates a new iterator that points to the predecessor of the current
 // node.
 //
 // REQUIRES: !iter.NegativeLimit()

registry.go

@@ -35,6 +35,8 @@ func (registry *PipelineItemRegistry) Register(example PipelineItem) {
 	}
 }
 
+// Summon searches for PipelineItem-s which provide the specified entity or named after
+// the specified string. It materializes all the found types and returns them.
 func (registry *PipelineItemRegistry) Summon(providesOrName string) []PipelineItem {
 	if registry.provided == nil {
 		return []PipelineItem{}
@@ -50,6 +52,7 @@ func (registry *PipelineItemRegistry) Summon(providesOrName string) []PipelineIt
 	return items
 }
 
+// GetLeaves returns all LeafPipelineItem-s registered.
 func (registry *PipelineItemRegistry) GetLeaves() []LeafPipelineItem {
 	keys := []string{}
 	for key := range registry.flags {
@@ -63,6 +66,7 @@ func (registry *PipelineItemRegistry) GetLeaves() []LeafPipelineItem {
 	return items
 }
 
+// GetPlumbingItems returns all non-LeafPipelineItem-s registered.
 func (registry *PipelineItemRegistry) GetPlumbingItems() []PipelineItem {
 	keys := []string{}
 	for key := range registry.registered {
@@ -95,6 +99,7 @@ func (ofi orderedFeaturedItems) Swap(i, j int) {
 	cofi[i], cofi[j] = cofi[j], cofi[i]
 }
 
+// GetFeaturedItems returns all FeaturedPipelineItem-s registered.
 func (registry *PipelineItemRegistry) GetFeaturedItems() map[string][]FeaturedPipelineItem {
 	features := map[string][]FeaturedPipelineItem{}
 	for _, t := range registry.registered {

renames.go

@@ -35,20 +35,28 @@ const (
 	ConfigRenameAnalysisSimilarityThreshold = "RenameAnalysis.SimilarityThreshold"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (ra *RenameAnalysis) Name() string {
 	return "RenameAnalysis"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (ra *RenameAnalysis) Provides() []string {
 	arr := [...]string{DependencyTreeChanges}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (ra *RenameAnalysis) Requires() []string {
 	arr := [...]string{DependencyBlobCache, DependencyTreeChanges}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (ra *RenameAnalysis) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigRenameAnalysisSimilarityThreshold,
@@ -60,12 +68,15 @@ func (ra *RenameAnalysis) ListConfigurationOptions() []ConfigurationOption {
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (ra *RenameAnalysis) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigRenameAnalysisSimilarityThreshold].(int); exists {
 		ra.SimilarityThreshold = val
 	}
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (ra *RenameAnalysis) Initialize(repository *git.Repository) {
 	if ra.SimilarityThreshold < 0 || ra.SimilarityThreshold > 100 {
 		fmt.Fprintf(os.Stderr, "Warning: adjusted the similarity threshold to %d\n",
@@ -75,6 +86,11 @@ func (ra *RenameAnalysis) Initialize(repository *git.Repository) {
 	ra.repository = repository
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (ra *RenameAnalysis) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	changes := deps[DependencyTreeChanges].(object.Changes)
 	cache := deps[DependencyBlobCache].(map[plumbing.Hash]*object.Blob)

shotness.go

@@ -68,26 +68,33 @@ func (node NodeSummary) String() string {
 	return node.InternalRole + "_" + node.Name + "_" + node.File
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (shotness *ShotnessAnalysis) Name() string {
 	return "Shotness"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (shotness *ShotnessAnalysis) Provides() []string {
 	return []string{}
 }
 
-func (shotness *ShotnessAnalysis) Features() []string {
-	arr := [...]string{FeatureUast}
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
+func (shotness *ShotnessAnalysis) Requires() []string {
+	arr := [...]string{DependencyFileDiff, DependencyUastChanges}
 	return arr[:]
 }
 
-func (shotness *ShotnessAnalysis) Requires() []string {
-	arr := [...]string{DependencyFileDiff, DependencyUastChanges}
+// Features which must be enabled for this PipelineItem to be automatically inserted into the DAG.
+func (shotness *ShotnessAnalysis) Features() []string {
+	arr := [...]string{FeatureUast}
 	return arr[:]
 }
 
-// ListConfigurationOptions tells the engine which parameters can be changed through the command
-// line.
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (shotness *ShotnessAnalysis) ListConfigurationOptions() []ConfigurationOption {
 	opts := [...]ConfigurationOption{{
 		Name:        ConfigShotnessXpathStruct,
@@ -109,7 +116,7 @@ func (shotness *ShotnessAnalysis) Flag() string {
 	return "shotness"
 }
 
-// Configure applies the parameters specified in the command line.
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (shotness *ShotnessAnalysis) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigShotnessXpathStruct]; exists {
 		shotness.XpathStruct = val.(string)
@@ -123,13 +130,18 @@ func (shotness *ShotnessAnalysis) Configure(facts map[string]interface{}) {
 	}
 }
 
-// Initialize resets the internal temporary data structures and prepares the object for Consume().
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (shotness *ShotnessAnalysis) Initialize(repository *git.Repository) {
 	shotness.nodes = map[string]*nodeShotness{}
 	shotness.files = map[string]map[string]*nodeShotness{}
 }
 
-// Consume is called for every commit in the sequence.
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (shotness *ShotnessAnalysis) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit)
 	changesList := deps[DependencyUastChanges].([]UASTChange)
@@ -307,7 +319,7 @@ func (shotness *ShotnessAnalysis) Consume(deps map[string]interface{}) (map[stri
 	return nil, nil
 }
 
-// Finalize produces the result of the analysis. No more Consume() calls are expected afterwards.
+// Finalize returns the result of the analysis. Further Consume() calls are not expected.
 func (shotness *ShotnessAnalysis) Finalize() interface{} {
 	result := ShotnessResult{
 		Nodes:    make([]NodeSummary, len(shotness.nodes)),
@@ -337,7 +349,8 @@ func (shotness *ShotnessAnalysis) Finalize() interface{} {
 	return result
 }
 
-// Serialize converts the result from Finalize() to either Protocol Buffers or YAML.
+// Serialize converts the analysis result as returned by Finalize() to text or bytes.
+// The text format is YAML and the bytes format is Protocol Buffers.
 func (shotness *ShotnessAnalysis) Serialize(result interface{}, binary bool, writer io.Writer) error {
 	shotnessResult := result.(ShotnessResult)
 	if binary {

toposort/toposort.go

@@ -261,6 +261,7 @@ func (g *Graph) Serialize(sorted []string) string {
 	return buffer.String()
 }
 
+// DebugDump converts the graph to a string. As the name suggests, useful for debugging.
 func (g *Graph) DebugDump() string {
 	S := make([]string, 0, len(g.outputs))
 	for n := range g.outputs {

tree_diff.go

@@ -20,29 +20,45 @@ const (
 	DependencyTreeChanges = "changes"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (treediff *TreeDiff) Name() string {
 	return "TreeDiff"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (treediff *TreeDiff) Provides() []string {
 	arr := [...]string{DependencyTreeChanges}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (treediff *TreeDiff) Requires() []string {
 	return []string{}
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (treediff *TreeDiff) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (treediff *TreeDiff) Configure(facts map[string]interface{}) {}
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (treediff *TreeDiff) Initialize(repository *git.Repository) {
 	treediff.previousTree = nil
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (treediff *TreeDiff) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	commit := deps["commit"].(*object.Commit)
 	tree, err := commit.Tree()

uast.go

@@ -92,25 +92,34 @@ func (w worker) Job(data interface{}) interface{} {
 	return w.Callback(task)
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (exr *UASTExtractor) Name() string {
 	return "UAST"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (exr *UASTExtractor) Provides() []string {
 	arr := [...]string{DependencyUasts}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (exr *UASTExtractor) Requires() []string {
 	arr := [...]string{DependencyTreeChanges, DependencyBlobCache}
 	return arr[:]
 }
 
+// Features which must be enabled for this PipelineItem to be automatically inserted into the DAG.
 func (exr *UASTExtractor) Features() []string {
 	arr := [...]string{FeatureUast}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (exr *UASTExtractor) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigUASTEndpoint,
@@ -142,6 +151,7 @@ func (exr *UASTExtractor) ListConfigurationOptions() []ConfigurationOption {
 	return options[:]
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (exr *UASTExtractor) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigUASTEndpoint].(string); exists {
 		exr.Endpoint = val
@@ -166,6 +176,8 @@ func (exr *UASTExtractor) Configure(facts map[string]interface{}) {
 	}
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (exr *UASTExtractor) Initialize(repository *git.Repository) {
 	if exr.Context == nil {
 		exr.Context = func() (context.Context, context.CancelFunc) {
@@ -202,6 +214,11 @@ func (exr *UASTExtractor) Initialize(repository *git.Repository) {
 	}
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (exr *UASTExtractor) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	cache := deps[DependencyBlobCache].(map[plumbing.Hash]*object.Blob)
 	treeDiffs := deps[DependencyTreeChanges].(object.Changes)
@@ -332,35 +349,52 @@ type UASTChanges struct {
 	cache map[plumbing.Hash]*uast.Node
 }
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (uc *UASTChanges) Name() string {
 	return "UASTChanges"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (uc *UASTChanges) Provides() []string {
 	arr := [...]string{DependencyUastChanges}
 	return arr[:]
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (uc *UASTChanges) Requires() []string {
 	arr := [...]string{DependencyUasts, DependencyTreeChanges}
 	return arr[:]
 }
 
+// Features which must be enabled for this PipelineItem to be automatically inserted into the DAG.
 func (uc *UASTChanges) Features() []string {
 	arr := [...]string{FeatureUast}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (uc *UASTChanges) ListConfigurationOptions() []ConfigurationOption {
 	return []ConfigurationOption{}
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (uc *UASTChanges) Configure(facts map[string]interface{}) {}
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (uc *UASTChanges) Initialize(repository *git.Repository) {
 	uc.cache = map[plumbing.Hash]*uast.Node{}
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (uc *UASTChanges) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	uasts := deps[DependencyUasts].(map[plumbing.Hash]*uast.Node)
 	treeDiffs := deps[DependencyTreeChanges].(object.Changes)
@@ -408,24 +442,33 @@ const (
 	ConfigUASTChangesSaverOutputPath = "UASTChangesSaver.OutputPath"
 )
 
+// Name of this PipelineItem. Uniquely identifies the type, used for mapping keys, etc.
 func (saver *UASTChangesSaver) Name() string {
 	return "UASTChangesSaver"
 }
 
+// Provides returns the list of names of entities which are produced by this PipelineItem.
+// Each produced entity will be inserted into `deps` of dependent Consume()-s according
+// to this list. Also used by hercules.Registry to build the global map of providers.
 func (saver *UASTChangesSaver) Provides() []string {
 	return []string{}
 }
 
+// Requires returns the list of names of entities which are needed by this PipelineItem.
+// Each requested entity will be inserted into `deps` of Consume(). In turn, those
+// entities are Provides() upstream.
 func (saver *UASTChangesSaver) Requires() []string {
 	arr := [...]string{DependencyUastChanges}
 	return arr[:]
 }
 
+// Features which must be enabled for this PipelineItem to be automatically inserted into the DAG.
 func (saver *UASTChangesSaver) Features() []string {
 	arr := [...]string{FeatureUast}
 	return arr[:]
 }
 
+// ListConfigurationOptions returns the list of changeable public properties of this PipelineItem.
 func (saver *UASTChangesSaver) ListConfigurationOptions() []ConfigurationOption {
 	options := [...]ConfigurationOption{{
 		Name:        ConfigUASTChangesSaverOutputPath,
@@ -437,31 +480,43 @@ func (saver *UASTChangesSaver) ListConfigurationOptions() []ConfigurationOption
 	return options[:]
 }
 
+// Flag for the command line switch which enables this analysis.
 func (saver *UASTChangesSaver) Flag() string {
 	return "dump-uast-changes"
 }
 
+// Configure sets the properties previously published by ListConfigurationOptions().
 func (saver *UASTChangesSaver) Configure(facts map[string]interface{}) {
 	if val, exists := facts[ConfigUASTChangesSaverOutputPath]; exists {
 		saver.OutputPath = val.(string)
 	}
 }
 
+// Initialize resets the temporary caches and prepares this PipelineItem for a series of Consume()
+// calls. The repository which is going to be analysed is supplied as an argument.
 func (saver *UASTChangesSaver) Initialize(repository *git.Repository) {
 	saver.repository = repository
 	saver.result = [][]UASTChange{}
 }
 
+// Consume runs this PipelineItem on the next commit data.
+// `deps` contain all the results from upstream PipelineItem-s as requested by Requires().
+// Additionally, "commit" is always present there and represents the analysed *object.Commit.
+// This function returns the mapping with analysis results. The keys must be the same as
+// in Provides(). If there was an error, nil is returned.
 func (saver *UASTChangesSaver) Consume(deps map[string]interface{}) (map[string]interface{}, error) {
 	changes := deps[DependencyUastChanges].([]UASTChange)
 	saver.result = append(saver.result, changes)
 	return nil, nil
 }
 
+// Finalize returns the result of the analysis. Further Consume() calls are not expected.
 func (saver *UASTChangesSaver) Finalize() interface{} {
 	return saver.result
 }
 
+// Serialize converts the analysis result as returned by Finalize() to text or bytes.
+// The text format is YAML and the bytes format is Protocol Buffers.
 func (saver *UASTChangesSaver) Serialize(result interface{}, binary bool, writer io.Writer) error {
 	saverResult := result.([][]UASTChange)
 	fileNames := saver.dumpFiles(saverResult)