docs(executor, parser): move README content to package comments (#85)

README.md

@@ -116,58 +116,6 @@ HealthCheck currently includes, `reposize`, `forbidden file`, `Metafile existenc
 
 The workflow is `joj3` pass cli args to healthcheck binary. See `./cmd/healthcheck/main.go` to view all flags.
 
-### Executors (under `/internal/executors`)
-
-#### Dummy
-
-Do not execute any command. Just return empty `ExecutorResult` slice.
-
-#### Sandbox
-
-Run the commands in `go-judge` and output the `ExecutorResult` slice. Note: we communicate with `go-judge` using gRPC, which means `go-judge` can run anywhere as the gRPC connection can be established. In deployment, `go-judge` runs in the host machine of the Gitea runner.
-
-### Parsers (under `/internal/parsers`)
-
-#### Clang Tidy
-
-Parser for `clang-tidy`, check `/examples/clangtidy` on how to call `clang-tidy` with proper parameters.
-
-#### Cppcheck
-
-Parser for `cppcheck`, check `/examples/cppcheck` on how to call `cppcheck` with proper parameters.
-
-#### Cpplint
-
-Parser for `cpplint`, check `/examples/cpplint` on how to call `cpplint` with proper parameters.
-
-#### Diff
-
-Compare the specified output of `ExecutorResult` with the content of the answer file. If they are the same, then score will be given. Just like a normal online judge system.
-
-#### Dummy
-
-Does not parse the output of `ExecutorResult`. It just output what is set inside the configuration file as score and comment. Currently it is used to output metadata for `joint-teapot`.
-
-In `joint-teapot`, it will take the content before `-` of the comment of the first stage with name `metadata` as the exercise name and record in the scoreboard. (e.g. If the comment is `p2-s2-0xdeadbeef`, then the exercise name is `p2`.)
-
-The comment in `metadata` can also be used to skip teapot commands. With `skip-teapot` in the comment, teapot will not run. And with `skip-scoreboard`, `skip-failed-table`, and `skip-result-issue`, only the corresponding step will be skipped, while the others will be executed. (e.g. If the comment is `p2-s2-0xdeadbeef-skip-scoreboard-skip-result-issue`, then only failed table step in teapot will run.)
-
-#### Healthcheck
-
-Parser for the `healthcheck` binary mentioned before.
-
-#### Keyword
-
-Match the given keyword from the specified output of `ExecutorResult`. For each match, a deduction of score is given. Can be useful if we do not have a specific parser for a code quality tool. Check `/examples/keyword`.
-
-#### Result Status
-
-Only check if all the status of the executor is `StatusAccepted`. Can be used to check whether the command run in the executor exit normally.
-
-#### Sample
-
-Parser for the `sample` binary mentioned before. Only used as a sample.
-
 ## Models (for developers only)
 
 The program parses the configuration file to run multiple stages.

internal/executor/dummy/meta.go

@@ -1,3 +1,6 @@
+// Package dummy provides a mock executor implementation for testing purposes
+// and serves as a template for new executor development. It always returns
+// a empty accepted result.
 package dummy
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/executor/local/meta.go

@@ -1,3 +1,6 @@
+// Package local implements an executor that runs commands directly on the local
+// system. It passes current environment variables to the command, which can be
+// used for passing run time parameters.
 package local
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/executor/sandbox/meta.go

@@ -1,3 +1,7 @@
+// Package sandbox provides a sandboxed execution environment for running
+// untrusted code. It integrates with the go-judge execution service to provide
+// isolated and secure code execution. By default, it uses gRPC to communicate
+// with go-judge.
 package sandbox
 
 import (

internal/parser/clangtidy/meta.go

@@ -1,3 +1,5 @@
+// Package clangtidy parses output of the clang-tidy C/C++ linter tool to assign
+// scores based on detected code issues.
 package clangtidy
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/cppcheck/meta.go

@@ -1,3 +1,6 @@
+// Package clangtidy parses output of the cppcheck static analysis tool to
+// assign scores based on detected code issues.
+// Check examples on running cppcheck for parseable output.
 package cppcheck
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/cpplint/meta.go

@@ -1,3 +1,5 @@
+// Package clangtidy parses output of the cpplint style checker tool to assign
+// scores based on detected code issues.
 package cpplint
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/debug/meta.go

@@ -1,3 +1,4 @@
+// Package debug logs the executor result to help in troubleshooting.
 package debug
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/diff/meta.go

@@ -1,3 +1,6 @@
+// Package diff implements string comparison functionality for the specific
+// output files, comparing then with expected answers and assigning scores based
+// on results.
 package diff
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/dummy/meta.go

@@ -1,3 +1,5 @@
+// Package dummy provides a simple parser implementation that serves as a
+// template for new parser development.
 package dummy
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/healthcheck/meta.go

@@ -1,3 +1,5 @@
+// Package healthcheck parses the output of the repo-health-checker tool and
+// return forced quit status on error.
 package healthcheck
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/keyword/meta.go

@@ -1,3 +1,5 @@
+// Package keyword implements keyword-based output analysis functionality.
+// It evaluates output files by searching for specific keywords and assigns scores based on matches.
 package keyword
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/log/meta.go

@@ -1,3 +1,5 @@
+// Package log logs the json key-value pairs from given file. The log can be
+// used for Loki that contains run time status.
 package log
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/resultdetail/meta.go

@@ -1,3 +1,4 @@
+// Package resultdetail provides detailed execution result output.
 package resultdetail
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/resultstatus/meta.go

@@ -1,3 +1,6 @@
+// Package resultstatus provides functionality to parse execution results
+// and determine success/failure status. It can return forced quit status
+// when a non-accepted status is encountered.
 package resultstatus
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"

internal/parser/sample/meta.go

@@ -1,3 +1,5 @@
+// Package sample provides functionality to parse and process sample outputs
+// from stdout and stderr of the sample program. Use this as a sample.
 package sample
 
 import "github.com/joint-online-judge/JOJ3/internal/stage"