diff --git a/.gitignore b/.gitignore index 19f13c8..405f893 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,7 @@ /coverage.txt /gomarkdoc /bin/ -README-test.md +README-*-test.md # editor and IDE paraphernalia .vscode/* diff --git a/cmd/gomarkdoc/command_test.go b/cmd/gomarkdoc/command_test.go index 273df54..2d86b0c 100644 --- a/cmd/gomarkdoc/command_test.go +++ b/cmd/gomarkdoc/command_test.go @@ -29,18 +29,12 @@ func TestCommand(t *testing.T) { err := os.Chdir(filepath.Join(wd, "../../testData")) is.NoErr(err) - os.Args = []string{ + harness(t, test, []string{ "gomarkdoc", test, - "-o", "{{.Dir}}/README-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", - } - cleanup(test) - - main() - - verify(t, test) + }) }) } } @@ -54,12 +48,12 @@ func TestCommand_check(t *testing.T) { os.Args = []string{ "gomarkdoc", "./simple", "-c", - "-o", "{{.Dir}}/README.md", + "-o", "{{.Dir}}/README-github.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("simple") + cleanup(t, "simple") main() } @@ -72,18 +66,18 @@ func TestCommand_nested(t *testing.T) { os.Args = []string{ "gomarkdoc", "./nested/...", - "-o", "{{.Dir}}/README-test.md", + "-o", "{{.Dir}}/README-github-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("nested") - cleanup("nested/inner") + cleanup(t, "nested") + cleanup(t, "nested/inner") main() - verify(t, "nested") - verify(t, "nested/inner") + verify(t, "nested", "github") + verify(t, "nested/inner", "github") } func TestCommand_unexported(t *testing.T) { @@ -92,19 +86,14 @@ func TestCommand_unexported(t *testing.T) { err := os.Chdir(filepath.Join(wd, "../../testData")) is.NoErr(err) - os.Args = []string{ + harness(t, "unexported", []string{ "gomarkdoc", "./unexported", "-u", "-o", "{{.Dir}}/README-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", - } - cleanup("unexported") - - main() - - verify(t, "unexported") + }) } func TestCommand_version(t *testing.T) { @@ -142,7 +131,7 @@ func TestCommand_invalidCheck(t *testing.T) { "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("simple") + cleanup(t, "simple") cmd := buildCommand() err = cmd.Execute() @@ -157,18 +146,12 @@ func TestCommand_defaultDirectory(t *testing.T) { err := os.Chdir(filepath.Join(wd, "../../testData/simple")) is.NoErr(err) - os.Args = []string{ + harness(t, ".", []string{ "gomarkdoc", - "-o", "{{.Dir}}/README-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/simple/", - } - cleanup(".") - - main() - - verify(t, ".") + }) } func TestCommand_nonexistant(t *testing.T) { @@ -197,21 +180,13 @@ func TestCommand_tags(t *testing.T) { err := os.Chdir(filepath.Join(wd, "../../testData")) is.NoErr(err) - os.Args = []string{ + harness(t, "tags", []string{ "gomarkdoc", "./tags", "--tags", "tagged", - "-o", "{{.Dir}}/README-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", - } - cleanup("tags") - - cmd := buildCommand() - err = cmd.Execute() - is.NoErr(err) - - verify(t, "./tags") + }) } func TestCommand_tagsWithGOFLAGS(t *testing.T) { @@ -224,18 +199,18 @@ func TestCommand_tagsWithGOFLAGS(t *testing.T) { os.Args = []string{ "gomarkdoc", "./tags", "--config", "../.gomarkdoc-empty.yml", - "-o", "{{.Dir}}/README-test.md", + "-o", "{{.Dir}}/README-github-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("tags") + cleanup(t, "tags") cmd := buildCommand() err = cmd.Execute() is.NoErr(err) - verify(t, "./tags") + verify(t, "./tags", "github") } func TestCommand_tagsWithGOFLAGSNoTags(t *testing.T) { @@ -250,18 +225,18 @@ func TestCommand_tagsWithGOFLAGSNoTags(t *testing.T) { os.Args = []string{ "gomarkdoc", "./tags", "--config", "../.gomarkdoc-empty.yml", - "-o", "{{.Dir}}/README-test.md", + "-o", "{{.Dir}}/README-github-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("tags") + cleanup(t, "tags") cmd := buildCommand() err = cmd.Execute() is.NoErr(err) - verifyNotEqual(t, "./tags") + verifyNotEqual(t, "./tags", "github") } func TestCommand_tagsWithGOFLAGSNoParse(t *testing.T) { @@ -276,18 +251,18 @@ func TestCommand_tagsWithGOFLAGSNoParse(t *testing.T) { os.Args = []string{ "gomarkdoc", "./tags", "--config", "../.gomarkdoc-empty.yml", - "-o", "{{.Dir}}/README-test.md", + "-o", "{{.Dir}}/README-github-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("tags") + cleanup(t, "tags") cmd := buildCommand() err = cmd.Execute() is.NoErr(err) - verifyNotEqual(t, "./tags") + verifyNotEqual(t, "./tags", "github") } func TestCommand_embed(t *testing.T) { @@ -299,22 +274,22 @@ func TestCommand_embed(t *testing.T) { os.Args = []string{ "gomarkdoc", "./embed", "--embed", - "-o", "{{.Dir}}/README-test.md", + "-o", "{{.Dir}}/README-github-test.md", "--repository.url", "https://github.com/princjef/gomarkdoc", "--repository.default-branch", "master", "--repository.path", "/testData/", } - cleanup("embed") + cleanup(t, "embed") data, err := os.ReadFile("./embed/README-template.md") is.NoErr(err) - err = os.WriteFile("./embed/README-test.md", data, 0664) + err = os.WriteFile("./embed/README-github-test.md", data, 0664) is.NoErr(err) main() - verify(t, "./embed") + verify(t, "./embed", "github") } func TestCompare(t *testing.T) { @@ -346,30 +321,62 @@ func TestCompare(t *testing.T) { } } -func verify(t *testing.T, dir string) { +func verify(t *testing.T, dir, format string) { is := is.New(t) - data, err := os.ReadFile(filepath.Join(dir, "README.md")) + data, err := os.ReadFile(filepath.Join(dir, fmt.Sprintf("README-%s.md", format))) is.NoErr(err) - data2, err := os.ReadFile(filepath.Join(dir, "README-test.md")) + data2, err := os.ReadFile(filepath.Join(dir, fmt.Sprintf("README-%s-test.md", format))) is.NoErr(err) is.Equal(string(data), string(data2)) } -func verifyNotEqual(t *testing.T, dir string) { +func verifyNotEqual(t *testing.T, dir, format string) { is := is.New(t) - data, err := os.ReadFile(filepath.Join(dir, "README.md")) + data, err := os.ReadFile(filepath.Join(dir, fmt.Sprintf("README-%s.md", format))) is.NoErr(err) - data2, err := os.ReadFile(filepath.Join(dir, "README-test.md")) + data2, err := os.ReadFile(filepath.Join(dir, fmt.Sprintf("README-%s-test.md", format))) is.NoErr(err) is.True(string(data) != string(data2)) } -func cleanup(dir string) { - os.Remove(filepath.Join(dir, "README-test.md")) +func cleanup(t *testing.T, dir string) { + f, err := os.ReadDir(dir) + if err != nil { + t.Fatal(err) + } + + for _, n := range f { + if n.IsDir() { + continue + } + + if !strings.HasPrefix(n.Name(), "README") || !strings.HasSuffix(n.Name(), "-test.md") { + continue + } + + os.Remove(filepath.Join(dir, n.Name())) + + } +} + +// harness runs the test for all formats. Omit the --output and --format args to +// the command when running this as it will fill them in for you +func harness(t *testing.T, dir string, args []string) { + for _, format := range []string{"plain", "github", "azure-devops"} { + os.Args = args + os.Args = append(os.Args, "-o", fmt.Sprintf("{{.Dir}}/README-%s-test.md", format)) + os.Args = append(os.Args, "--format", format) + + cleanup(t, dir) + + main() + + verify(t, dir, format) + } } diff --git a/magefile.go b/magefile.go index ac15d59..8e708b2 100644 --- a/magefile.go +++ b/magefile.go @@ -64,7 +64,15 @@ func RegenerateTestDocs() error { } os.Chdir(filepath.Join(base, "./testData", dir.Name())) - if err := shellcmd.Command(`go run ../../cmd/gomarkdoc -o "{{.Dir}}/README.md" ./...`).Run(); err != nil { + if err := shellcmd.Command(`go run ../../cmd/gomarkdoc -o "{{.Dir}}/README-github.md" --format github ./...`).Run(); err != nil { + return err + } + + if err := shellcmd.Command(`go run ../../cmd/gomarkdoc -o "{{.Dir}}/README-plain.md" --format plain ./...`).Run(); err != nil { + return err + } + + if err := shellcmd.Command(`go run ../../cmd/gomarkdoc -o "{{.Dir}}/README-azure-devops.md" --format azure-devops ./...`).Run(); err != nil { return err } } diff --git a/testData/docs/README-azure-devops.md b/testData/docs/README-azure-devops.md new file mode 100644 index 0000000..de582f7 --- /dev/null +++ b/testData/docs/README-azure-devops.md @@ -0,0 +1,170 @@ + + +# docs + +```go +import "github.com/princjef/gomarkdoc/testData/docs" +``` + +Package docs exercises the documentation features of golang 1.19 and above at the package documentation level. + +### This is a heading + +This heading has a paragraph with a reference to the standard library [math/rand]() as well as a function in the file [Func](<#Func>), a type [Type](<#Type>), a type's function [Type.Func](<#Type.Func>), a non\-standard library package [golang.org/x/crypto/bcrypt.Cost](), an external link [Outside Link]() and a \[broken link\]. We can also place links directly like https://github.com which get turned into links. + +It also has a numbered list: + +1. First +2. Second +3. Third + +Plus one with blank lines: + +1. First + +2. Second + +3. Third + +Non\-numbered lists + +- First another line +- Second +- Third + +Plus blank lines: + +- First + + another paragraph + +- Second + +- Third + +And a golang code block: + +``` +func GolangCode(t int) int { + return t + 1 +} +``` + +And a random code block: + +``` +something + preformatted +in a random + way +``` + +There's also another file with a struct called [AnotherStruct](<#AnotherStruct>) that has additional methods and fields. + +We also have constants like [Constant](<#Constant>) and [Const1](<#Const1>) plus variables like [Var](<#Var>) and and [VarB](<#VarA>). + +## Index + +- [Constants](<#constants>) +- [Variables](<#variables>) +- [func Func\(param int\) int](<#Func>) +- [type AnotherStruct](<#AnotherStruct>) + - [func NewAnotherStruct\(\) \*AnotherStruct](<#NewAnotherStruct>) + - [func \(s \*AnotherStruct\) GetField\(\) string](<#AnotherStruct.GetField>) +- [type Type](<#Type>) + - [func \(t \*Type\) Func\(\)](<#Type.Func>) + + +## Constants + +This is a constant block + +```go +const ( + Const1 = 1 + Const2 = 2 + Const3 = 3 +) +``` + +Constant is a constant. + +```go +const Constant = 3 +``` + +## Variables + +This is a var block + +```go +var ( + VarA = 'a' + VarB = 'b' + VarC = 'c' +) +``` + +Var is a var. + +```go +var Var = 2 +``` + + +## func [Func]() + +```go +func Func(param int) int +``` + +Func is present in this file. + + +## type [AnotherStruct]() + +AnotherStruct has methods like [\\\*AnotherStruct.GetField](<#AnotherStruct.GetField>) and also has an initializer called [NewAnotherStruct](<#NewAnotherStruct>). + +```go +type AnotherStruct struct { + Field string +} +``` + + +### func [NewAnotherStruct]() + +```go +func NewAnotherStruct() *AnotherStruct +``` + +NewAnotherStruct\(\) makes [\\\*AnotherStruct](<#AnotherStruct>). + + +### func \(\*AnotherStruct\) [GetField]() + +```go +func (s *AnotherStruct) GetField() string +``` + +GetField gets \[\*AnotherStruct.Field\]. + + +## type [Type]() + +Type is a type in this file. + +```go +type Type struct{} +``` + + +### func \(\*Type\) [Func]() + +```go +func (t *Type) Func() +``` + +TypeFunc is a func within a type in this file. + +Generated by [gomarkdoc]() diff --git a/testData/docs/README.md b/testData/docs/README-github.md similarity index 94% rename from testData/docs/README.md rename to testData/docs/README-github.md index 5fe3dfb..30d245a 100644 --- a/testData/docs/README.md +++ b/testData/docs/README-github.md @@ -10,7 +10,7 @@ Package docs exercises the documentation features of golang 1.19 and above at th ### This is a heading -This heading has a paragraph with a reference to the standard library [math/rand]() as well as a function in the file [Func](<#Func>), a type [Type](<#Type>), a type's function [Type.Func](<#Type.Func>), a non\-standard library package [golang.org/x/crypto/bcrypt.Cost](), an external link [Outside Link]() and a \[broken link\]. +This heading has a paragraph with a reference to the standard library [math/rand]() as well as a function in the file [Func](<#Func>), a type [Type](<#Type>), a type's function [Type.Func](<#Type.Func>), a non\-standard library package [golang.org/x/crypto/bcrypt.Cost](), an external link [Outside Link]() and a \[broken link\]. We can also place links directly like https://github.com which get turned into links. It also has a numbered list: @@ -112,7 +112,7 @@ var Var = 2 ``` -## func [Func]() +## func [Func]() ```go func Func(param int) int @@ -150,7 +150,7 @@ func (s *AnotherStruct) GetField() string GetField gets \[\*AnotherStruct.Field\]. -## type [Type]() +## type [Type]() Type is a type in this file. @@ -159,7 +159,7 @@ type Type struct{} ``` -### func \(\*Type\) [Func]() +### func \(\*Type\) [Func]() ```go func (t *Type) Func() diff --git a/testData/docs/README-plain.md b/testData/docs/README-plain.md new file mode 100644 index 0000000..9f9d88c --- /dev/null +++ b/testData/docs/README-plain.md @@ -0,0 +1,146 @@ + + +# docs + + import "github.com/princjef/gomarkdoc/testData/docs" + +Package docs exercises the documentation features of golang 1.19 and above at the package documentation level. + +### This is a heading + +This heading has a paragraph with a reference to the standard library [math/rand]() as well as a function in the file [Func](<#Func>), a type [Type](<#Type>), a type's function [Type.Func](<#Type.Func>), a non\-standard library package [golang.org/x/crypto/bcrypt.Cost](), an external link [Outside Link]() and a \[broken link\]. We can also place links directly like https://github.com which get turned into links. + +It also has a numbered list: + +1. First +2. Second +3. Third + +Plus one with blank lines: + +1. First + +2. Second + +3. Third + +Non\-numbered lists + +- First another line +- Second +- Third + +Plus blank lines: + +- First + + another paragraph + +- Second + +- Third + +And a golang code block: + + func GolangCode(t int) int { + return t + 1 + } + + +And a random code block: + + something + preformatted + in a random + way + + +There's also another file with a struct called [AnotherStruct](<#AnotherStruct>) that has additional methods and fields. + +We also have constants like [Constant](<#Constant>) and [Const1](<#Const1>) plus variables like [Var](<#Var>) and and [VarB](<#VarA>). + +## Index + +- Constants +- Variables +- [func Func\(param int\) int](<#Func>) +- [type AnotherStruct](<#AnotherStruct>) + - [func NewAnotherStruct\(\) \*AnotherStruct](<#NewAnotherStruct>) + - [func \(s \*AnotherStruct\) GetField\(\) string](<#AnotherStruct.GetField>) +- [type Type](<#Type>) + - [func \(t \*Type\) Func\(\)](<#Type.Func>) + + +## Constants + +This is a constant block + + const ( + Const1 = 1 + Const2 = 2 + Const3 = 3 + ) + +Constant is a constant. + + const Constant = 3 + +## Variables + +This is a var block + + var ( + VarA = 'a' + VarB = 'b' + VarC = 'c' + ) + +Var is a var. + + var Var = 2 + + +## func Func + + func Func(param int) int + +Func is present in this file. + + +## type AnotherStruct + +AnotherStruct has methods like [\\\*AnotherStruct.GetField](<#AnotherStruct.GetField>) and also has an initializer called [NewAnotherStruct](<#NewAnotherStruct>). + + type AnotherStruct struct { + Field string + } + + +### func NewAnotherStruct + + func NewAnotherStruct() *AnotherStruct + +NewAnotherStruct\(\) makes [\\\*AnotherStruct](<#AnotherStruct>). + + +### func \(\*AnotherStruct\) GetField + + func (s *AnotherStruct) GetField() string + +GetField gets \[\*AnotherStruct.Field\]. + + +## type Type + +Type is a type in this file. + + type Type struct{} + + +### func \(\*Type\) Func + + func (t *Type) Func() + +TypeFunc is a func within a type in this file. + +Generated by [gomarkdoc]() diff --git a/testData/docs/docs.go b/testData/docs/docs.go index 12f9fdf..41e86a5 100644 --- a/testData/docs/docs.go +++ b/testData/docs/docs.go @@ -7,7 +7,8 @@ // [math/rand] as well as a function in the file [Func], a type [Type], a type's // function [Type.Func], a non-standard library package // [golang.org/x/crypto/bcrypt.Cost], an external link [Outside Link] and -// a [broken link]. +// a [broken link]. We can also place links directly like https://github.com +// which get turned into links. // // It also has a numbered list: // 1. First diff --git a/testData/embed/README-azure-devops.md b/testData/embed/README-azure-devops.md new file mode 100644 index 0000000..f9cfd95 --- /dev/null +++ b/testData/embed/README-azure-devops.md @@ -0,0 +1,100 @@ +This is content before the embed + + + + + +# embed + +```go +import "github.com/princjef/gomarkdoc/testData/embed" +``` + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func [EmbeddedFunc]() + +```go +func EmbeddedFunc(param int) int +``` + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the embed + + + + + +# embed + +```go +import "github.com/princjef/gomarkdoc/testData/embed" +``` + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func [EmbeddedFunc]() + +```go +func EmbeddedFunc(param int) int +``` + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the second embed + + + + + +# embed + +```go +import "github.com/princjef/gomarkdoc/testData/embed" +``` + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func [EmbeddedFunc]() + +```go +func EmbeddedFunc(param int) int +``` + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the third embed \ No newline at end of file diff --git a/testData/embed/README.md b/testData/embed/README-github.md similarity index 100% rename from testData/embed/README.md rename to testData/embed/README-github.md diff --git a/testData/embed/README-plain.md b/testData/embed/README-plain.md new file mode 100644 index 0000000..2eca968 --- /dev/null +++ b/testData/embed/README-plain.md @@ -0,0 +1,88 @@ +This is content before the embed + + + + + +# embed + + import "github.com/princjef/gomarkdoc/testData/embed" + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func EmbeddedFunc + + func EmbeddedFunc(param int) int + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the embed + + + + + +# embed + + import "github.com/princjef/gomarkdoc/testData/embed" + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func EmbeddedFunc + + func EmbeddedFunc(param int) int + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the second embed + + + + + +# embed + + import "github.com/princjef/gomarkdoc/testData/embed" + +Package embed tests out embedding of documentation in an existing readme. + +## Index + +- [func EmbeddedFunc\(param int\) int](<#EmbeddedFunc>) + + + +## func EmbeddedFunc + + func EmbeddedFunc(param int) int + +EmbeddedFunc is present in embedded content. + +Generated by [gomarkdoc]() + + + + +This is content after the third embed \ No newline at end of file diff --git a/testData/generics/README-azure-devops.md b/testData/generics/README-azure-devops.md new file mode 100644 index 0000000..a2e9378 --- /dev/null +++ b/testData/generics/README-azure-devops.md @@ -0,0 +1,55 @@ + + +# generics + +```go +import "github.com/princjef/gomarkdoc/testData/generics" +``` + +## Index + +- [func Func\[S int | float64\]\(s S\) S](<#Func>) +- [type Generic](<#Generic>) + - [func NewGeneric\[T any\]\(param T\) Generic\[T\]](<#NewGeneric>) + - [func \(g Generic\[T\]\) Method\(\)](<#Generic[T].Method>) + + + +## func [Func]() + +```go +func Func[S int | float64](s S) S +``` + +Func is a generic function. + + +## type [Generic]() + +Generic is a generic struct. + +```go +type Generic[T any] struct { + Field T +} +``` + + +### func [NewGeneric]() + +```go +func NewGeneric[T any](param T) Generic[T] +``` + +NewGeneric produces a new [Generic](<#Generic>) struct. + + +### func \(Generic\[T\]\) [Method]() + +```go +func (g Generic[T]) Method() +``` + +Method is a method of a generic type. + +Generated by [gomarkdoc]() diff --git a/testData/generics/README.md b/testData/generics/README-github.md similarity index 100% rename from testData/generics/README.md rename to testData/generics/README-github.md diff --git a/testData/generics/README-plain.md b/testData/generics/README-plain.md new file mode 100644 index 0000000..df3e3e9 --- /dev/null +++ b/testData/generics/README-plain.md @@ -0,0 +1,45 @@ + + +# generics + + import "github.com/princjef/gomarkdoc/testData/generics" + +## Index + +- [func Func\[S int | float64\]\(s S\) S](<#Func>) +- [type Generic](<#Generic>) + - [func NewGeneric\[T any\]\(param T\) Generic\[T\]](<#NewGeneric>) + - [func \(g Generic\[T\]\) Method\(\)](<#Generic[T].Method>) + + + +## func Func + + func Func[S int | float64](s S) S + +Func is a generic function. + + +## type Generic + +Generic is a generic struct. + + type Generic[T any] struct { + Field T + } + + +### func NewGeneric + + func NewGeneric[T any](param T) Generic[T] + +NewGeneric produces a new [Generic](<#Generic>) struct. + + +### func \(Generic\[T\]\) Method + + func (g Generic[T]) Method() + +Method is a method of a generic type. + +Generated by [gomarkdoc]() diff --git a/testData/lang/function/README-azure-devops.md b/testData/lang/function/README-azure-devops.md new file mode 100644 index 0000000..d593586 --- /dev/null +++ b/testData/lang/function/README-azure-devops.md @@ -0,0 +1,241 @@ + + +# function + +```go +import "github.com/princjef/gomarkdoc/testData/lang/function" +``` + +## Index + +- [Constants](<#constants>) +- [Variables](<#variables>) +- [func Standalone\(p1 int, p2 string\) \(int, error\)](<#Standalone>) +- [type Generic](<#Generic>) + - [func \(r Generic\[T\]\) WithGenericReceiver\(\)](<#Generic[T].WithGenericReceiver>) +- [type Receiver](<#Receiver>) + - [func New\(\) Receiver](<#New>) + - [func \(r \*Receiver\) WithPtrReceiver\(\)](<#Receiver.WithPtrReceiver>) + - [func \(r Receiver\) WithReceiver\(\)](<#Receiver.WithReceiver>) + + +## Constants + +Set of constants for this package. + +```go +const ( + ConstA = "string" + ConstB = true +) +``` + +## Variables + +Variable is a package\-level variable. + +```go +var Variable = 5 +``` + + +## func [Standalone]() + +```go +func Standalone(p1 int, p2 string) (int, error) +``` + +Standalone provides a function that is not part of a type. + +Additional description can be provided in subsequent paragraphs, including code blocks and headers + +### Header A + +This section contains a code block. + +``` +Code Block +More of Code Block +``` + +
Example +

+ + + +```go +package main + +import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" +) + +func main() { + // Comment + res, _ := function.Standalone(2, "abc") + fmt.Println(res) +} +``` + +#### Output + +``` +2 +``` + +

+
+ +
Example (Zero) +

+ + + +```go +package main + +import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" +) + +func main() { + res, _ := function.Standalone(0, "def") + fmt.Println(res) +} +``` + +#### Output + +``` +0 +``` + +

+
+ + +## type [Generic]() + +Generic is a struct with a generic type. + +```go +type Generic[T any] struct{} +``` + + +### func \(Generic\[T\]\) [WithGenericReceiver]() + +```go +func (r Generic[T]) WithGenericReceiver() +``` + +WithGenericReceiver has a receiver with a generic type. + +
Example +

+ + + +```go +package main + +import ( + "github.com/princjef/gomarkdoc/testData/lang/function" +) + +func main() { + r := function.Generic[int]{} + r.WithGenericReceiver() +} +``` + +

+
+ + +## type [Receiver]() + +Receiver is a type used to demonstrate functions with receivers. + +```go +type Receiver struct{} +``` + +
Example +

+ + + +```go +package main + +import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" +) + +func main() { + // Add some comments + r := &function.Receiver{} + // And some more + fmt.Println(r) +} +``` + +

+
+ +
Example (Sub Test) +

+ + + +```go +package main + +import ( + "github.com/princjef/gomarkdoc/testData/lang/function" +) + +func main() { + var r function.Receiver + r.WithReceiver() +} +``` + +

+
+ + +### func [New]() + +```go +func New() Receiver +``` + +New is an initializer for Receiver. + + +### func \(\*Receiver\) [WithPtrReceiver]() + +```go +func (r *Receiver) WithPtrReceiver() +``` + +WithPtrReceiver has a pointer receiver. + + +### func \(Receiver\) [WithReceiver]() + +```go +func (r Receiver) WithReceiver() +``` + +WithReceiver has a receiver. + +Generated by [gomarkdoc]() diff --git a/testData/lang/function/README.md b/testData/lang/function/README-github.md similarity index 100% rename from testData/lang/function/README.md rename to testData/lang/function/README-github.md diff --git a/testData/lang/function/README-plain.md b/testData/lang/function/README-plain.md new file mode 100644 index 0000000..09b1391 --- /dev/null +++ b/testData/lang/function/README-plain.md @@ -0,0 +1,213 @@ + + +# function + + import "github.com/princjef/gomarkdoc/testData/lang/function" + +## Index + +- Constants +- Variables +- [func Standalone\(p1 int, p2 string\) \(int, error\)](<#Standalone>) +- [type Generic](<#Generic>) + - [func \(r Generic\[T\]\) WithGenericReceiver\(\)](<#Generic[T].WithGenericReceiver>) +- [type Receiver](<#Receiver>) + - [func New\(\) Receiver](<#New>) + - [func \(r \*Receiver\) WithPtrReceiver\(\)](<#Receiver.WithPtrReceiver>) + - [func \(r Receiver\) WithReceiver\(\)](<#Receiver.WithReceiver>) + + +## Constants + +Set of constants for this package. + + const ( + ConstA = "string" + ConstB = true + ) + +## Variables + +Variable is a package\-level variable. + + var Variable = 5 + + +## func Standalone + + func Standalone(p1 int, p2 string) (int, error) + +Standalone provides a function that is not part of a type. + +Additional description can be provided in subsequent paragraphs, including code blocks and headers + +### Header A + +This section contains a code block. + + Code Block + More of Code Block + + +###### Example + + + + package main + + import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" + ) + + func main() { + // Comment + res, _ := function.Standalone(2, "abc") + fmt.Println(res) + } + + +#### Output + + 2 + + + + + + +###### Example (Zero) + + + + package main + + import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" + ) + + func main() { + res, _ := function.Standalone(0, "def") + fmt.Println(res) + } + + +#### Output + + 0 + + + + + + + +## type Generic + +Generic is a struct with a generic type. + + type Generic[T any] struct{} + + +### func \(Generic\[T\]\) WithGenericReceiver + + func (r Generic[T]) WithGenericReceiver() + +WithGenericReceiver has a receiver with a generic type. + +###### Example + + + + package main + + import ( + "github.com/princjef/gomarkdoc/testData/lang/function" + ) + + func main() { + r := function.Generic[int]{} + r.WithGenericReceiver() + } + + + + + + + +## type Receiver + +Receiver is a type used to demonstrate functions with receivers. + + type Receiver struct{} + +###### Example + + + + package main + + import ( + "fmt" + + "github.com/princjef/gomarkdoc/testData/lang/function" + ) + + func main() { + // Add some comments + r := &function.Receiver{} + // And some more + fmt.Println(r) + } + + + + + + +###### Example (Sub Test) + + + + package main + + import ( + "github.com/princjef/gomarkdoc/testData/lang/function" + ) + + func main() { + var r function.Receiver + r.WithReceiver() + } + + + + + + + +### func New + + func New() Receiver + +New is an initializer for Receiver. + + +### func \(\*Receiver\) WithPtrReceiver + + func (r *Receiver) WithPtrReceiver() + +WithPtrReceiver has a pointer receiver. + + +### func \(Receiver\) WithReceiver + + func (r Receiver) WithReceiver() + +WithReceiver has a receiver. + +Generated by [gomarkdoc]() diff --git a/testData/nested/README-azure-devops.md b/testData/nested/README-azure-devops.md new file mode 100644 index 0000000..f2c53c5 --- /dev/null +++ b/testData/nested/README-azure-devops.md @@ -0,0 +1,23 @@ + + +# nested + +```go +import "github.com/princjef/gomarkdoc/testData/nested" +``` + +## Index + +- [func Parent\(\) int](<#Parent>) + + + +## func [Parent]() + +```go +func Parent() int +``` + +Parent is in the parent package. + +Generated by [gomarkdoc]() diff --git a/testData/nested/README.md b/testData/nested/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/nested/README.md rename to testData/nested/README-github.md diff --git a/testData/nested/README-plain.md b/testData/nested/README-plain.md new file mode 100644 index 0000000..f7a4569 --- /dev/null +++ b/testData/nested/README-plain.md @@ -0,0 +1,19 @@ + + +# nested + + import "github.com/princjef/gomarkdoc/testData/nested" + +## Index + +- [func Parent\(\) int](<#Parent>) + + + +## func Parent + + func Parent() int + +Parent is in the parent package. + +Generated by [gomarkdoc]() diff --git a/testData/nested/inner/README-azure-devops.md b/testData/nested/inner/README-azure-devops.md new file mode 100644 index 0000000..5aa0c4e --- /dev/null +++ b/testData/nested/inner/README-azure-devops.md @@ -0,0 +1,23 @@ + + +# inner + +```go +import "github.com/princjef/gomarkdoc/testData/nested/inner" +``` + +## Index + +- [func Child\(\) int](<#Child>) + + + +## func [Child]() + +```go +func Child() int +``` + +Child is in the child package. + +Generated by [gomarkdoc]() diff --git a/testData/nested/inner/README.md b/testData/nested/inner/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/nested/inner/README.md rename to testData/nested/inner/README-github.md diff --git a/testData/nested/inner/README-plain.md b/testData/nested/inner/README-plain.md new file mode 100644 index 0000000..e4a5cb1 --- /dev/null +++ b/testData/nested/inner/README-plain.md @@ -0,0 +1,19 @@ + + +# inner + + import "github.com/princjef/gomarkdoc/testData/nested/inner" + +## Index + +- [func Child\(\) int](<#Child>) + + + +## func Child + + func Child() int + +Child is in the child package. + +Generated by [gomarkdoc]() diff --git a/testData/simple/README-azure-devops.md b/testData/simple/README-azure-devops.md new file mode 100644 index 0000000..ba70959 --- /dev/null +++ b/testData/simple/README-azure-devops.md @@ -0,0 +1,47 @@ + + +# simple + +```go +import "github.com/princjef/gomarkdoc/testData/simple" +``` + +Package simple contains, some simple code to exercise basic scenarios for documentation purposes. + +## Index + +- [type Num](<#Num>) + - [func AddNums\(num1, num2 Num\) Num](<#AddNums>) + - [func \(n Num\) Add\(num Num\) Num](<#Num.Add>) + + + +## type [Num]() + +Num is a number. + +It is just a test type so that we can make sure this works. + +```go +type Num int +``` + + +### func [AddNums]() + +```go +func AddNums(num1, num2 Num) Num +``` + +AddNums adds two Nums together. + + +### func \(Num\) [Add]() + +```go +func (n Num) Add(num Num) Num +``` + +Add adds the other num to this one. + +Generated by [gomarkdoc]() diff --git a/testData/simple/README.md b/testData/simple/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/simple/README.md rename to testData/simple/README-github.md diff --git a/testData/simple/README-plain.md b/testData/simple/README-plain.md new file mode 100644 index 0000000..fd11bb3 --- /dev/null +++ b/testData/simple/README-plain.md @@ -0,0 +1,39 @@ + + +# simple + + import "github.com/princjef/gomarkdoc/testData/simple" + +Package simple contains, some simple code to exercise basic scenarios for documentation purposes. + +## Index + +- [type Num](<#Num>) + - [func AddNums\(num1, num2 Num\) Num](<#AddNums>) + - [func \(n Num\) Add\(num Num\) Num](<#Num.Add>) + + + +## type Num + +Num is a number. + +It is just a test type so that we can make sure this works. + + type Num int + + +### func AddNums + + func AddNums(num1, num2 Num) Num + +AddNums adds two Nums together. + + +### func \(Num\) Add + + func (n Num) Add(num Num) Num + +Add adds the other num to this one. + +Generated by [gomarkdoc]() diff --git a/testData/tags/README-azure-devops.md b/testData/tags/README-azure-devops.md new file mode 100644 index 0000000..d18bf0d --- /dev/null +++ b/testData/tags/README-azure-devops.md @@ -0,0 +1,35 @@ + + +# tags + +```go +import "github.com/princjef/gomarkdoc/testData/tags" +``` + +Package tags contains code to demonstrate usage of build tags. + +## Index + +- [func Tagged\(\) int](<#Tagged>) +- [func Untagged\(\) int](<#Untagged>) + + + +## func [Tagged]() + +```go +func Tagged() int +``` + +Tagged is only visible with tags. + + +## func [Untagged]() + +```go +func Untagged() int +``` + +Untagged is visible without tags. + +Generated by [gomarkdoc]() diff --git a/testData/tags/README.md b/testData/tags/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/tags/README.md rename to testData/tags/README-github.md diff --git a/testData/tags/README-plain.md b/testData/tags/README-plain.md new file mode 100644 index 0000000..3516688 --- /dev/null +++ b/testData/tags/README-plain.md @@ -0,0 +1,29 @@ + + +# tags + + import "github.com/princjef/gomarkdoc/testData/tags" + +Package tags contains code to demonstrate usage of build tags. + +## Index + +- [func Tagged\(\) int](<#Tagged>) +- [func Untagged\(\) int](<#Untagged>) + + + +## func Tagged + + func Tagged() int + +Tagged is only visible with tags. + + +## func Untagged + + func Untagged() int + +Untagged is visible without tags. + +Generated by [gomarkdoc]() diff --git a/testData/unexported/README-azure-devops.md b/testData/unexported/README-azure-devops.md new file mode 100644 index 0000000..0ebecb7 --- /dev/null +++ b/testData/unexported/README-azure-devops.md @@ -0,0 +1,57 @@ + + +# unexported + +```go +import "github.com/princjef/gomarkdoc/testData/unexported" +``` + +Package unexported contains some simple code to exercise basic scenarios for documentation purposes. + +## Index + +- [type Num](<#Num>) + - [func AddNums\(num1, num2 Num\) Num](<#AddNums>) + - [func addInternal\(num1, num2 Num\) Num](<#addInternal>) + - [func \(n Num\) Add\(num Num\) Num](<#Num.Add>) + + + +## type [Num]() + +Num is a number. + +It is just a test type so that we can make sure this works. + +```go +type Num int +``` + + +### func [AddNums]() + +```go +func AddNums(num1, num2 Num) Num +``` + +AddNums adds two Nums together. + + +### func [addInternal]() + +```go +func addInternal(num1, num2 Num) Num +``` + +addInternal is a private version of AddNums. + + +### func \(Num\) [Add]() + +```go +func (n Num) Add(num Num) Num +``` + +Add adds the other num to this one. + +Generated by [gomarkdoc]() diff --git a/testData/unexported/README.md b/testData/unexported/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/unexported/README.md rename to testData/unexported/README-github.md diff --git a/testData/unexported/README-plain.md b/testData/unexported/README-plain.md new file mode 100644 index 0000000..c2da334 --- /dev/null +++ b/testData/unexported/README-plain.md @@ -0,0 +1,47 @@ + + +# unexported + + import "github.com/princjef/gomarkdoc/testData/unexported" + +Package unexported contains some simple code to exercise basic scenarios for documentation purposes. + +## Index + +- [type Num](<#Num>) + - [func AddNums\(num1, num2 Num\) Num](<#AddNums>) + - [func addInternal\(num1, num2 Num\) Num](<#addInternal>) + - [func \(n Num\) Add\(num Num\) Num](<#Num.Add>) + + + +## type Num + +Num is a number. + +It is just a test type so that we can make sure this works. + + type Num int + + +### func AddNums + + func AddNums(num1, num2 Num) Num + +AddNums adds two Nums together. + + +### func addInternal + + func addInternal(num1, num2 Num) Num + +addInternal is a private version of AddNums. + + +### func \(Num\) Add + + func (n Num) Add(num Num) Num + +Add adds the other num to this one. + +Generated by [gomarkdoc]() diff --git a/testData/untagged/README-azure-devops.md b/testData/untagged/README-azure-devops.md new file mode 100644 index 0000000..c996cd5 --- /dev/null +++ b/testData/untagged/README-azure-devops.md @@ -0,0 +1,25 @@ + + +# untagged + +```go +import "github.com/princjef/gomarkdoc/testData/untagged" +``` + +Package untagged contains code to demonstrate usage of build tags. + +## Index + +- [func Untagged\(\) int](<#Untagged>) + + + +## func [Untagged]() + +```go +func Untagged() int +``` + +Untagged is visible without tags. + +Generated by [gomarkdoc]() diff --git a/testData/untagged/README.md b/testData/untagged/README-github.md old mode 100755 new mode 100644 similarity index 100% rename from testData/untagged/README.md rename to testData/untagged/README-github.md diff --git a/testData/untagged/README-plain.md b/testData/untagged/README-plain.md new file mode 100644 index 0000000..8ea9376 --- /dev/null +++ b/testData/untagged/README-plain.md @@ -0,0 +1,21 @@ + + +# untagged + + import "github.com/princjef/gomarkdoc/testData/untagged" + +Package untagged contains code to demonstrate usage of build tags. + +## Index + +- [func Untagged\(\) int](<#Untagged>) + + + +## func Untagged + + func Untagged() int + +Untagged is visible without tags. + +Generated by [gomarkdoc]()