The comment parser api provides 2 endpoints

GET /?package={Package Name such as "fmt"}&tokens={comma seperated values}

Test /package=fmt&tokens=TODO,voodoo

POST /parse

This API requires a model that satisfies

type CommentParsingRequest struct {
	PackageName string
	Tokens      []string
}

Naturally, you will need to specify the header "Content-Type" as "application/json"

Result format

Both the endpoints use the following result formats in json

// the result model for Comment Parsing
type CommentParsingResult struct {
	PackageName string                      // the package name in which the matches were made
	BinaryOnly  bool                        // true if the package was binary only
	Matches     map[string][]MatchedComment // the matched comments
}

// result model for a single matched comment
type MatchedComment struct {
	FileName    string // the file name where the comment was found
	LineNumber  int    // the line number where the comment was found
	LineContent string // the content of the comment itself
}

The API can be started either with the provided shell script in scripts/devserver.sh, else by manually running go run main.go server path_to_config or the compiled bin bin/commentparser server path_to_config

It is possible to provide no configs, however in that case the application will attempt to find the cofiguration file in ~/configuration/development.json

The configuration file is expected to have this json format

type Configuration struct {
	Development          bool   // true if the application is in development mode, false in production
	Address              string // the address to bind the server to
	LogName              string // path to log to
	GoogleCloudProjectID string // the google cloud project ID
	GoogleCloudCredFile  string // google cloud API credentials file
}

Development: When this false, the API will sanitize any error that is not marked Sanitized Address: The address to use for the API. Since the application is designed to be used inside a docker container avoid specifying more than a port like ":8080" LogName: The log name to use for logging on Stackdriver GoogleCloudProjectID: The ID of the Google Cloud Project GoogleCloudCredFile: This credential file is used by the Stack driver client to connect to the Stackdriver API

TODO: If no CloudCredentialFile is provided, donot use Stackdriver for logging

The application is capable of handing Binary-Only libraries. If a binary only library is detected, the BinaryOnly flag in the CommentParsingResult will be set to true. This will result in no matches. An example binary-only library is referenced in the tests and can be tested online with

Test github.com/tcnksm/go-binary-only-package/src/github.com/tcnksm/hello

The program can be run locally by providing two parameters

1. The Package Name
2. (Optional) Comma Seperated Values of tokens/words to search for

Examples

go run main.go fmt TODO,example

go run main.go log TODO,example,os

Below are some comments to aid in the development for the project. This project uses docker containers for rapid deployment to Google Container Resgistry and from there to VMs. Besides simply running the application you can test it within the containers.

docker build -t gcr.io/{vm-tag-name}/cp-dev-docker-1:1.1 -f docker/Dockerfile.dev .

docker run --expose=8080 -p8080:8080 -t gcr.io/{vm-tag-name}/cp-dev-docker-1:1.1 ./scripts/devserver.sh

If you make any change to the port on which the API runs, you will need to make appropriate changes to the command's expose and -p arguments

docker push gcr.io/{vm-tag-name}/cp-dev-docker-1:1.1

To be fair you can choose to use any tag you wish to. Before doing any of this you will need get gcloud which will act as an authentication helper for docker to upload to *.gcr.io. Please note that each image requires paid storage space - it is best to delete container images you donot need.

To see the logs generated by the API you will need to set up Stackdriver in your Google Cloud Project. Ensure that your VM has access to the Stackdriver API (most of the time VMs are given Stackdriver Write Access by default)

You should see something along these lines

TODO: Increase the time units of API performance measurement