docs: document job type

docs-types
sammyette 2023-01-07 12:35:06 -04:00
parent 07a7a75b46
commit a4dea1aefd
Signed by: sammyette
GPG Key ID: 904FC49417B44DCD
6 changed files with 174 additions and 29 deletions

View File

@ -7,6 +7,7 @@ import (
"go/doc"
"go/parser"
"go/token"
"regexp"
"strings"
"os"
"sync"
@ -31,6 +32,7 @@ type emmyPiece struct {
}
type module struct {
Types []docPiece
Docs []docPiece
Fields []docPiece
Properties []docPiece
@ -38,6 +40,7 @@ type module struct {
Description string
ParentModule string
HasInterfaces bool
HasTypes bool
}
type docPiece struct {
@ -49,6 +52,7 @@ type docPiece struct {
GoFuncName string
IsInterface bool
IsMember bool
IsType bool
Fields []docPiece
Properties []docPiece
}
@ -119,6 +123,69 @@ func docPieceTag(tagName string, tags map[string][]tag) []docPiece {
return dps
}
func setupDocType(mod string, typ *doc.Type) *docPiece {
docs := strings.TrimSpace(typ.Doc)
inInterface := strings.HasPrefix(docs, "#interface")
if !inInterface {
return nil
}
tags, doc := getTagsAndDocs(docs)
var interfaces string
typeName := strings.ToUpper(string(typ.Name[0])) + typ.Name[1:]
typeDoc := []string{}
if inInterface {
interfaces = tags["interface"][0].id
}
fields := docPieceTag("field", tags)
properties := docPieceTag("property", tags)
for _, d := range doc {
if strings.HasPrefix(d, "---") {
// TODO: document types in lua
/*
emmyLine := strings.TrimSpace(strings.TrimPrefix(d, "---"))
emmyLinePieces := strings.Split(emmyLine, " ")
emmyType := emmyLinePieces[0]
if emmyType == "@param" {
em.Params = append(em.Params, emmyLinePieces[1])
}
if emmyType == "@vararg" {
em.Params = append(em.Params, "...") // add vararg
}
em.Annotations = append(em.Annotations, d)
*/
} else {
typeDoc = append(typeDoc, d)
}
}
var isMember bool
if tags["member"] != nil {
isMember = true
}
var parentMod string
if inInterface {
parentMod = mod
}
dps := &docPiece{
Doc: typeDoc,
FuncName: typeName,
Interfacing: interfaces,
IsInterface: inInterface,
IsMember: isMember,
IsType: true,
ParentModule: parentMod,
Fields: fields,
Properties: properties,
}
return dps
}
func setupDoc(mod string, fun *doc.Func) *docPiece {
docs := strings.TrimSpace(fun.Doc)
inInterface := strings.HasPrefix(docs, "#interface")
@ -220,6 +287,7 @@ func main() {
for l, f := range pkgs {
p := doc.New(f, "./", doc.AllDecls)
pieces := []docPiece{}
typePieces := []docPiece{}
mod := l
if mod == "main" {
mod = "hilbish"
@ -237,6 +305,14 @@ func main() {
}
}
for _, t := range p.Types {
typePiece := setupDocType(mod, t)
if typePiece != nil {
typePieces = append(typePieces, *typePiece)
if typePiece.IsInterface {
hasInterfaces = true
}
}
for _, m := range t.Methods {
piece := setupDoc(mod, m)
if piece == nil {
@ -254,6 +330,7 @@ func main() {
shortDesc := descParts[0]
desc := descParts[1:]
filteredPieces := []docPiece{}
filteredTypePieces := []docPiece{}
for _, piece := range pieces {
if !piece.IsInterface {
filteredPieces = append(filteredPieces, piece)
@ -276,10 +353,28 @@ func main() {
interfaceModules[modname].Properties = piece.Properties
continue
}
interfaceModules[modname].Docs = append(interfaceModules[modname].Docs, piece)
}
for _, piece := range typePieces {
if !piece.IsInterface {
filteredTypePieces = append(filteredTypePieces, piece)
continue
}
modname := piece.ParentModule + "." + piece.Interfacing
if interfaceModules[modname] == nil {
interfaceModules[modname] = &module{
ParentModule: piece.ParentModule,
}
}
interfaceModules[modname].Types = append(interfaceModules[modname].Types, piece)
}
docs[mod] = module{
Types: filteredTypePieces,
Docs: filteredPieces,
ShortDescription: shortDesc,
Description: strings.Join(desc, "\n"),
@ -335,11 +430,39 @@ func main() {
}
f.WriteString("\n")
}
if len(modu.Docs) != 0 {
f.WriteString("## Functions\n")
if len(modu.Types) != 0 {
f.WriteString("## Types\n")
for _, dps := range modu.Types {
f.WriteString(fmt.Sprintf("### %s\n", dps.FuncName))
for _, doc := range dps.Doc {
if !strings.HasPrefix(doc, "---") {
f.WriteString(doc + "\n")
}
}
if len(dps.Properties) != 0 {
f.WriteString("#### Properties\n")
for _, dps := range dps.Properties {
f.WriteString(fmt.Sprintf("- `%s`: ", dps.FuncName))
f.WriteString(strings.Join(dps.Doc, " "))
f.WriteString("\n")
}
}
f.WriteString("\n")
}
}
if len(modu.Docs) != 0 {
typeTag, _ := regexp.Compile(`@\w+`)
f.WriteString("## Functions\n")
for _, dps := range modu.Docs {
f.WriteString(fmt.Sprintf("### %s\n", dps.FuncSig))
htmlSig := typeTag.ReplaceAllStringFunc(strings.Replace(dps.FuncSig, "<", `\<`, -1), func(typ string) string {
// todo: get type from global table to link to
// other pages (hilbish page can link to hilbish.jobs#Job)
typName := typ[1:]
linkedTyp := strings.ToLower(typName) // TODO: link
return fmt.Sprintf(`<a href="#%s" style="text-decoration: none;">%s</a>`, linkedTyp, typName)
})
f.WriteString(fmt.Sprintf("### %s\n", htmlSig))
for _, doc := range dps.Doc {
if !strings.HasPrefix(doc, "---") {
f.WriteString(doc + "\n")
@ -347,6 +470,7 @@ func main() {
}
f.WriteString("\n")
}
}
}(mod, docPath, v)
go func(md, modname string, modu module) {

View File

@ -17,9 +17,8 @@ This is an alias (ha) for the `hilbish.alias` function.
### delete(name)
Removes an alias.
### list() -> aliases (table)
### list() -> table\<string, string>
Get a table of all aliases, with string keys as the alias and the value as the command.
@returns table<string, string>
### resolve(alias) -> command (string)
Tries to resolve an alias to its command.

View File

@ -14,7 +14,10 @@ Manage interactive jobs in Hilbish via Lua.
Jobs are the name of background tasks/commands. A job can be started via
interactive usage or with the functions defined below for use in external runners.
## Object properties
## Types
### Job
Job Type.
#### Properties
- `cmd`: The user entered command string for the job.
- `running`: Whether the job is running or not.
- `id`: The ID of the job in the job table
@ -40,15 +43,15 @@ Stops the job from running.
### add(cmdstr, args, execPath)
Adds a new job to the job table. Note that this does not immediately run it.
### all() -> jobs (table<Job/Table>)
### all() -> table\<<a href="#job" style="text-decoration: none;">Job</a>>
Returns a table of all job objects.
### disown(id)
Disowns a job. This deletes it from the job table.
### get(id) -> job (Job/Table)
### get(id) -> <a href="#job" style="text-decoration: none;">Job</a>
Get a job object via its ID.
### last() -> job (Job/Table)
### last() -> <a href="#job" style="text-decoration: none;">Job</a>
Returns the last added job from the table.

22
job.go
View File

@ -18,6 +18,15 @@ import (
var jobs *jobHandler
var jobMetaKey = rt.StringValue("hshjob")
// #interface jobs
// #property cmd The user entered command string for the job.
// #property running Whether the job is running or not.
// #property id The ID of the job in the job table
// #property pid The Process ID
// #property exitCode The last exit code of the job.
// #property stdout The standard output of the job. This just means the normal logs of the process.
// #property stderr The standard error stream of the process. This (usually) includes error messages of the job.
// Job Type.
type job struct {
cmd string
running bool
@ -293,13 +302,6 @@ func (j *jobHandler) stopAll() {
}
// #interface jobs
// #property cmd The user entered command string for the job.
// #property running Whether the job is running or not.
// #property id The ID of the job in the job table
// #property pid The Process ID
// #property exitCode The last exit code of the job.
// #property stdout The standard output of the job. This just means the normal logs of the process.
// #property stderr The standard error stream of the process. This (usually) includes error messages of the job.
// background job management
/*
Manage interactive jobs in Hilbish via Lua.
@ -384,7 +386,7 @@ func jobUserData(j *job) *rt.UserData {
}
// #interface jobs
// get(id) -> job (Job/Table)
// get(id) -> @Job
// Get a job object via its ID.
// --- @param id number
// --- @returns Job
@ -444,7 +446,7 @@ func (j *jobHandler) luaAddJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface jobs
// all() -> jobs (table<Job/Table>)
// all() -> table<@Job>
// Returns a table of all job objects.
// --- @returns table<Job>
func (j *jobHandler) luaAllJobs(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
@ -481,7 +483,7 @@ func (j *jobHandler) luaDisownJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {
}
// #interface jobs
// last() -> job (Job/Table)
// last() -> @Job
// Returns the last added job from the table.
// --- @returns Job
func (j *jobHandler) luaLastJob(t *rt.Thread, c *rt.GoCont) (rt.Cont, error) {

View File

@ -1,6 +1,11 @@
<h{{ (add .Level 1) }} id="{{ .Anchor | safeURL }}">
<h{{ (add .Level 1) }} id="{{ .Anchor | safeURL }}" class="heading">
{{ .Text | safeHTML }}
<a href="#{{ .Anchor | safeURL }}" class='heading-link'>
<i class="fas fa-paperclip"></i>
</a>
</h{{ (add .Level 1) }}>
{{ if eq .Text ""}}
<hr>
{{ end }}

View File

@ -23,4 +23,16 @@
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/js/bootstrap.bundle.min.js" integrity="sha384-pprn3073KE6tl6bjs2QrFaJGz5/SUsLqktiwsUTF55Jfv3qYSDhgCecCxMW52nD2" crossorigin="anonymous"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.1/css/all.min.css" integrity="sha512-KfkfwYDsLkIlwQp6LFnl8zNdLGxu9YAA1QvwINks4PhcElQSvqcyVLLD9aMhXd13uQjoXtEKNosOWaZqXgel0g==" crossorigin="anonymous" referrerpolicy="no-referrer" />
<style>
.heading > .heading-link {
opacity: 0
}
.heading:hover > .heading-link {
visibility: visible;
opacity: 1;
transition: all .1s ease-in;
}
</style>
</head>