From 4118600b753eddd6080bf38e4b54f6d0ea5199bc Mon Sep 17 00:00:00 2001 From: Daniel Barria Date: Thu, 7 Jul 2022 02:59:44 -0400 Subject: [PATCH] fix(format): remove dot and colon characters from escape function (#70) --- README.md | 62 ++++++------ cmd/gomarkdoc/README.md | 6 +- format/README.md | 90 +++++++++--------- format/formatcore/README.md | 26 ++--- format/formatcore/base.go | 2 +- format/formatcore/base_test.go | 4 +- lang/README.md | 164 ++++++++++++++++---------------- testData/embed/README.md | 12 +-- testData/nested/README.md | 2 +- testData/nested/inner/README.md | 2 +- testData/simple/README.md | 10 +- testData/simple/main.go | 2 +- testData/tags/README.md | 6 +- testData/unexported/README.md | 12 +-- testData/untagged/README.md | 4 +- 15 files changed, 202 insertions(+), 202 deletions(-) diff --git a/README.md b/README.md index e28cdc3..aa0906e 100644 --- a/README.md +++ b/README.md @@ -11,17 +11,17 @@ import "github.com/princjef/gomarkdoc" ``` -Package gomarkdoc formats documentation for one or more packages as markdown for usage outside of the main https://pkg.go.dev site\. It supports custom templates for tweaking representation of documentation at fine\-grained levels\, exporting both exported and unexported symbols\, and custom formatters for different backends\. +Package gomarkdoc formats documentation for one or more packages as markdown for usage outside of the main https://pkg.go.dev site. It supports custom templates for tweaking representation of documentation at fine\-grained levels, exporting both exported and unexported symbols, and custom formatters for different backends. ### Command Line Usage -If you want to use this package as a command\-line tool\, you can install the command by running the following on go 1\.16\+: +If you want to use this package as a command\-line tool, you can install the command by running the following on go 1.16\+: ``` go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest ``` -For older versions of go\, you can install using the following method instead: +For older versions of go, you can install using the following method instead: ``` GO111MODULE=on go get -u github.com/princjef/gomarkdoc/cmd/gomarkdoc @@ -58,7 +58,7 @@ Flags: --version Print the version. ``` -The gomarkdoc command processes each of the provided packages\, generating documentation for the package in markdown format and writing it to console\. For example\, if you have a package in your current directory and want to send it to a documentation markdown file\, you might do something like this: +The gomarkdoc command processes each of the provided packages, generating documentation for the package in markdown format and writing it to console. For example, if you have a package in your current directory and want to send it to a documentation markdown file, you might do something like this: ``` gomarkdoc --output doc.md . @@ -66,27 +66,27 @@ gomarkdoc --output doc.md . ### Package Specifiers -The gomarkdoc tool supports generating documentation for both local packages and remote ones\. To specify a local package\, start the name of the package with a period \(\.\) or specify an absolute path on the filesystem\. All other package signifiers are assumed to be remote packages\. You may specify both local and remote packages in the same command invocation as separate arguments\. +The gomarkdoc tool supports generating documentation for both local packages and remote ones. To specify a local package, start the name of the package with a period \(.\) or specify an absolute path on the filesystem. All other package signifiers are assumed to be remote packages. You may specify both local and remote packages in the same command invocation as separate arguments. ### Output Redirection -By default\, the documentation generated by the gomarkdoc command is sent to standard output\, where it can be redirected to a file\. This can be useful if you want to perform additional modifications to the documentation or send it somewhere other than a file\. However\, keep in mind that there are some inconsistencies in how various shells/platforms handle redirected command output \(for example\, Powershell encodes in UTF\-16\, not UTF\-8\)\. As a result\, the \-\-output option described below is recommended for most use cases\. +By default, the documentation generated by the gomarkdoc command is sent to standard output, where it can be redirected to a file. This can be useful if you want to perform additional modifications to the documentation or send it somewhere other than a file. However, keep in mind that there are some inconsistencies in how various shells/platforms handle redirected command output \(for example, Powershell encodes in UTF\-16, not UTF\-8\). As a result, the \-\-output option described below is recommended for most use cases. ``` gomarkdoc . > doc.md ``` -If you want to redirect output for each processed package to a file\, you can provide the \-\-output/\-o option\, which accepts a template specifying how to generate the path of the output file\. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the \.\.\. signifier as in other parts of the golang toolchain\)\. In addition\, this option provides consistent behavior across platforms and shells: +If you want to redirect output for each processed package to a file, you can provide the \-\-output/\-o option, which accepts a template specifying how to generate the path of the output file. A common usage of this option is when generating README documentation for a package with subpackages \(which are supported via the ... signifier as in other parts of the golang toolchain\). In addition, this option provides consistent behavior across platforms and shells: ``` gomarkdoc --output '{{.Dir}}/README.md' ./... ``` -You can see all of the data available to the output template in the PackageSpec struct in the github\.com/princjef/gomarkdoc/cmd/gomarkdoc package\. +You can see all of the data available to the output template in the PackageSpec struct in the github.com/princjef/gomarkdoc/cmd/gomarkdoc package. ### Template Overrides -The documentation information that is output is formatted using a series of text templates for the various components of the overall documentation which get generated\. Higher level templates contain lower level templates\, but any template may be replaced with an override template using the \-\-template/\-t option\. The full list of templates that may be overridden are: +The documentation information that is output is formatted using a series of text templates for the various components of the overall documentation which get generated. Higher level templates contain lower level templates, but any template may be replaced with an override template using the \-\-template/\-t option. The full list of templates that may be overridden are: ``` - file: generates documentation for a file containing one or more @@ -122,7 +122,7 @@ The documentation information that is output is formatted using a series of text - import: generates the import code used to pull in a package. ``` -Overriding with the \-t option uses a key\-vaule pair mapping a template name to the file containing the contents of the override template to use\. Specified template files must exist: +Overriding with the \-t option uses a key\-vaule pair mapping a template name to the file containing the contents of the override template to use. Specified template files must exist: ``` gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt . @@ -130,19 +130,19 @@ gomarkdoc -t package=custom-package.gotxt -t doc=custom-doc.gotxt . ### Additional Options -As with the godoc tool itself\, only exported symbols will be shown in documentation\. This can be expanded to include all symbols in a package by adding the \-\-include\-unexported/\-u flag\. +As with the godoc tool itself, only exported symbols will be shown in documentation. This can be expanded to include all symbols in a package by adding the \-\-include\-unexported/\-u flag. ``` gomarkdoc -u -o README.md . ``` -If you want to blend the documentation generated by gomarkdoc with your own hand\-written markdown\, you can use the \-\-embed/\-e flag to change the gomarkdoc tool into an append/embed mode\. When documentation is generated\, gomarkdoc looks for a file in the location where the documentation is to be written and embeds the documentation if present\. Otherwise\, the documentation is appended to the end of the file\. +If you want to blend the documentation generated by gomarkdoc with your own hand\-written markdown, you can use the \-\-embed/\-e flag to change the gomarkdoc tool into an append/embed mode. When documentation is generated, gomarkdoc looks for a file in the location where the documentation is to be written and embeds the documentation if present. Otherwise, the documentation is appended to the end of the file. ``` gomarkdoc -o README.md -e . ``` -When running with embed mode enabled\, gomarkdoc will look for either this single comment: +When running with embed mode enabled, gomarkdoc will look for either this single comment: ``` @@ -158,25 +158,25 @@ This content is replaced with the embedded documentation ``` -If you would like to include files that are part of a build tag\, you can specify build tags with the \-\-tags flag\. Tags are also supported through GOFLAGS\, though command line and configuration file definitions override tags specified through GOFLAGS\. +If you would like to include files that are part of a build tag, you can specify build tags with the \-\-tags flag. Tags are also supported through GOFLAGS, though command line and configuration file definitions override tags specified through GOFLAGS. ``` gomarkdoc --tags sometag . ``` -You can also run gomarkdoc in a verification mode with the \-\-check/\-c flag\. This is particularly useful for continuous integration when you want to make sure that a commit correctly updated the generated documentation\. This flag is only supported when the \-\-output/\-o flag is specified\, as the file provided there is what the tool is checking: +You can also run gomarkdoc in a verification mode with the \-\-check/\-c flag. This is particularly useful for continuous integration when you want to make sure that a commit correctly updated the generated documentation. This flag is only supported when the \-\-output/\-o flag is specified, as the file provided there is what the tool is checking: ``` gomarkdoc -o README.md -c . ``` -If you're experiencing difficulty with gomarkdoc or just want to get more information about how it's executing underneath\, you can add \-v to show more logs\. This can be chained a second time to show even more verbose logs: +If you're experiencing difficulty with gomarkdoc or just want to get more information about how it's executing underneath, you can add \-v to show more logs. This can be chained a second time to show even more verbose logs: ``` gomarkdoc -vv -o README.md . ``` -Some features of gomarkdoc rely on being able to detect information from the git repository containing the project\. Since individual local git repositories may be configured differently from person to person\, you may want to manually specify the information for the repository to remove any inconsistencies\. This can be achieved with the \-\-repository\.url\, \-\-repository\.default\-branch and \-\-repository\.path options\. For example\, this repository would be configured with: +Some features of gomarkdoc rely on being able to detect information from the git repository containing the project. Since individual local git repositories may be configured differently from person to person, you may want to manually specify the information for the repository to remove any inconsistencies. This can be achieved with the \-\-repository.url, \-\-repository.default\-branch and \-\-repository.path options. For example, this repository would be configured with: ``` gomarkdoc --repository.url "https://github.com/princjef/gomarkdoc" --repository.default-branch master --repository.path / -o README.md . @@ -184,13 +184,13 @@ gomarkdoc --repository.url "https://github.com/princjef/gomarkdoc" --repository. ### Configuring via File -If you want to reuse configuration options across multiple invocations\, you can specify a file in the folder where you invoke gomarkdoc containing configuration information that you would otherwise provide on the command line\. This file may be a JSON\, TOML\, YAML\, HCL\, env\, or Java properties file\, but the name is expected to start with \.gomarkdoc \(e\.g\. \.gomarkdoc\.yml\)\. +If you want to reuse configuration options across multiple invocations, you can specify a file in the folder where you invoke gomarkdoc containing configuration information that you would otherwise provide on the command line. This file may be a JSON, TOML, YAML, HCL, env, or Java properties file, but the name is expected to start with .gomarkdoc \(e.g. .gomarkdoc.yml\). -All configuration options are available with the camel\-cased form of their long name \(e\.g\. \-\-include\-unexported becomes includeUnexported\)\. Template overrides are specified as a map\, rather than a set of key\-value pairs separated by =\. Options provided on the command line override those provided in the configuration file if an option is present in both\. +All configuration options are available with the camel\-cased form of their long name \(e.g. \-\-include\-unexported becomes includeUnexported\). Template overrides are specified as a map, rather than a set of key\-value pairs separated by =. Options provided on the command line override those provided in the configuration file if an option is present in both. ### Programmatic Usage -While most users will find the command line utility sufficient for their needs\, this package may also be used programmatically by installing it directly\, rather than its command subpackage\. The programmatic usage provides more flexibility when selecting what packages to work with and what components to generate documentation for\. +While most users will find the command line utility sufficient for their needs, this package may also be used programmatically by installing it directly, rather than its command subpackage. The programmatic usage provides more flexibility when selecting what packages to work with and what components to generate documentation for. A common usage will look something like this: @@ -239,7 +239,7 @@ func main() { ### Examples -This project uses itself to generate the README files in github\.com/princjef/gomarkdoc and its subdirectories\. To see the commands that are run to generate documentation for this repository\, take a look at the Doc\(\) and DocVerify\(\) functions in magefile\.go and the \.gomarkdoc\.yml file in the root of this repository\. To run these commands in your own project\, simply replace \`go run \./cmd/gomarkdoc\` with \`gomarkdoc\`\. +This project uses itself to generate the README files in github.com/princjef/gomarkdoc and its subdirectories. To see the commands that are run to generate documentation for this repository, take a look at the Doc\(\) and DocVerify\(\) functions in magefile.go and the .gomarkdoc.yml file in the root of this repository. To run these commands in your own project, simply replace \`go run ./cmd/gomarkdoc\` with \`gomarkdoc\`. Know of another project that is using gomarkdoc? Open an issue with a description of the project and link to the repository and it might be featured here\! @@ -259,7 +259,7 @@ Know of another project that is using gomarkdoc? Open an issue with a descriptio ## type [Renderer]() -Renderer provides capabilities for rendering various types of documentation with the configured format and templates\. +Renderer provides capabilities for rendering various types of documentation with the configured format and templates. ```go type Renderer struct { @@ -273,7 +273,7 @@ type Renderer struct { func NewRenderer(opts ...RendererOption) (*Renderer, error) ``` -NewRenderer initializes a Renderer configured using the provided options\. If nothing special is provided\, the created renderer will use the default set of templates and the GitHubFlavoredMarkdown\. +NewRenderer initializes a Renderer configured using the provided options. If nothing special is provided, the created renderer will use the default set of templates and the GitHubFlavoredMarkdown. ### func \(\*Renderer\) [Example]() @@ -281,7 +281,7 @@ NewRenderer initializes a Renderer configured using the provided options\. If no func (out *Renderer) Example(ex *lang.Example) (string, error) ``` -Example renders an example's documentation to a string\. You can change the rendering of the example by overriding the "example" template or one of the templates it references\. +Example renders an example's documentation to a string. You can change the rendering of the example by overriding the "example" template or one of the templates it references. ### func \(\*Renderer\) [File]() @@ -289,7 +289,7 @@ Example renders an example's documentation to a string\. You can change the rend func (out *Renderer) File(file *lang.File) (string, error) ``` -File renders a file containing one or more packages to document to a string\. You can change the rendering of the file by overriding the "file" template or one of the templates it references\. +File renders a file containing one or more packages to document to a string. You can change the rendering of the file by overriding the "file" template or one of the templates it references. ### func \(\*Renderer\) [Func]() @@ -297,7 +297,7 @@ File renders a file containing one or more packages to document to a string\. Yo func (out *Renderer) Func(fn *lang.Func) (string, error) ``` -Func renders a function's documentation to a string\. You can change the rendering of the package by overriding the "func" template or one of the templates it references\. +Func renders a function's documentation to a string. You can change the rendering of the package by overriding the "func" template or one of the templates it references. ### func \(\*Renderer\) [Package]() @@ -305,7 +305,7 @@ Func renders a function's documentation to a string\. You can change the renderi func (out *Renderer) Package(pkg *lang.Package) (string, error) ``` -Package renders a package's documentation to a string\. You can change the rendering of the package by overriding the "package" template or one of the templates it references\. +Package renders a package's documentation to a string. You can change the rendering of the package by overriding the "package" template or one of the templates it references. ### func \(\*Renderer\) [Type]() @@ -313,11 +313,11 @@ Package renders a package's documentation to a string\. You can change the rende func (out *Renderer) Type(typ *lang.Type) (string, error) ``` -Type renders a type's documentation to a string\. You can change the rendering of the type by overriding the "type" template or one of the templates it references\. +Type renders a type's documentation to a string. You can change the rendering of the type by overriding the "type" template or one of the templates it references. ## type [RendererOption]() -RendererOption configures the renderer's behavior\. +RendererOption configures the renderer's behavior. ```go type RendererOption func(renderer *Renderer) error @@ -329,7 +329,7 @@ type RendererOption func(renderer *Renderer) error func WithFormat(format format.Format) RendererOption ``` -WithFormat changes the renderer to use the format provided instead of the default format\. +WithFormat changes the renderer to use the format provided instead of the default format. ### func [WithTemplateOverride]() @@ -337,7 +337,7 @@ WithFormat changes the renderer to use the format provided instead of the defaul func WithTemplateOverride(name, tmpl string) RendererOption ``` -WithTemplateOverride adds a template that overrides the template with the provided name using the value provided in the tmpl parameter\. +WithTemplateOverride adds a template that overrides the template with the provided name using the value provided in the tmpl parameter. diff --git a/cmd/gomarkdoc/README.md b/cmd/gomarkdoc/README.md index b6f5e41..926e5d3 100644 --- a/cmd/gomarkdoc/README.md +++ b/cmd/gomarkdoc/README.md @@ -6,9 +6,9 @@ import "github.com/princjef/gomarkdoc/cmd/gomarkdoc" ``` -Package gomarkdoc provides a command line interface for writing golang documentation in markdown format\. +Package gomarkdoc provides a command line interface for writing golang documentation in markdown format. -See https://github.com/princjef/gomarkdoc for full documentation of this tool\. +See https://github.com/princjef/gomarkdoc for full documentation of this tool. ## Index @@ -17,7 +17,7 @@ See https://github.com/princjef/gomarkdoc for full documentation of this tool\. ## type [PackageSpec]() -PackageSpec defines the data available to the \-\-output option's template\. Information is recomputed for each package generated\. +PackageSpec defines the data available to the \-\-output option's template. Information is recomputed for each package generated. ```go type PackageSpec struct { diff --git a/format/README.md b/format/README.md index 8ba4f22..d216aae 100755 --- a/format/README.md +++ b/format/README.md @@ -6,9 +6,9 @@ import "github.com/princjef/gomarkdoc/format" ``` -Package format defines output formats for emitting documentation information\. +Package format defines output formats for emitting documentation information. -Each of the formats in this package contains the same set of formatting functions\, but not all formats support all of the functions natively\. Where possible\, a fallback format is provided\. See the documentation for the individual formats for more information\. +Each of the formats in this package contains the same set of formatting functions, but not all formats support all of the functions natively. Where possible, a fallback format is provided. See the documentation for the individual formats for more information. ## Index @@ -59,7 +59,7 @@ Each of the formats in this package contains the same set of formatting function ## type [AzureDevOpsMarkdown]() -AzureDevOpsMarkdown provides a Format which is compatible with Azure DevOps's syntax and semantics\. See the Azure DevOps documentation for more details about their markdown format: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops +AzureDevOpsMarkdown provides a Format which is compatible with Azure DevOps's syntax and semantics. See the Azure DevOps documentation for more details about their markdown format: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops ```go type AzureDevOpsMarkdown struct{} @@ -71,7 +71,7 @@ type AzureDevOpsMarkdown struct{} func (f *AzureDevOpsMarkdown) Accordion(title, body string) (string, error) ``` -Accordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. +Accordion generates a collapsible content. The accordion's visible title while collapsed is the provided title and the expanded content is the body. ### func \(\*AzureDevOpsMarkdown\) [AccordionHeader]() @@ -79,9 +79,9 @@ Accordion generates a collapsible content\. The accordion's visible title while func (f *AzureDevOpsMarkdown) AccordionHeader(title string) (string, error) ``` -AccordionHeader generates the header visible when an accordion is collapsed\. +AccordionHeader generates the header visible when an accordion is collapsed. -The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently\. The result looks conceptually like the following: +The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following: ``` accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() @@ -93,7 +93,7 @@ accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + form func (f *AzureDevOpsMarkdown) AccordionTerminator() (string, error) ``` -AccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. +AccordionTerminator generates the code necessary to terminate an accordion after the body. It is expected to be used in conjunction with AccordionHeader\(\). See AccordionHeader for a full description. ### func \(\*AzureDevOpsMarkdown\) [Bold]() @@ -109,7 +109,7 @@ Bold converts the provided text to bold func (f *AzureDevOpsMarkdown) CodeBlock(language, code string) (string, error) ``` -CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\. +CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\). ### func \(\*AzureDevOpsMarkdown\) [CodeHref]() @@ -117,7 +117,7 @@ CodeBlock wraps the provided code as a code block and tags it with the provided func (f *AzureDevOpsMarkdown) CodeHref(loc lang.Location) (string, error) ``` -CodeHref generates an href to the provided code entry\. +CodeHref generates an href to the provided code entry. ### func \(\*AzureDevOpsMarkdown\) [Escape]() @@ -125,7 +125,7 @@ CodeHref generates an href to the provided code entry\. func (f *AzureDevOpsMarkdown) Escape(text string) string ``` -Escape escapes special markdown characters from the provided text\. +Escape escapes special markdown characters from the provided text. ### func \(\*AzureDevOpsMarkdown\) [Header]() @@ -133,7 +133,7 @@ Escape escapes special markdown characters from the provided text\. func (f *AzureDevOpsMarkdown) Header(level int, text string) (string, error) ``` -Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. +Header converts the provided text into a header of the provided level. The level is expected to be at least 1. ### func \(\*AzureDevOpsMarkdown\) [Link]() @@ -141,7 +141,7 @@ Header converts the provided text into a header of the provided level\. The leve func (f *AzureDevOpsMarkdown) Link(text, href string) (string, error) ``` -Link generates a link with the given text and href values\. +Link generates a link with the given text and href values. ### func \(\*AzureDevOpsMarkdown\) [ListEntry]() @@ -149,7 +149,7 @@ Link generates a link with the given text and href values\. func (f *AzureDevOpsMarkdown) ListEntry(depth int, text string) (string, error) ``` -ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. +ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth. A depth of 0 is considered the topmost level of list. ### func \(\*AzureDevOpsMarkdown\) [LocalHref]() @@ -157,7 +157,7 @@ ListEntry generates an unordered list entry with the provided text at the provid func (f *AzureDevOpsMarkdown) LocalHref(headerText string) (string, error) ``` -LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself\. Link generation follows the guidelines here: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#anchor-links +LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself. Link generation follows the guidelines here: https://docs.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops#anchor-links ### func \(\*AzureDevOpsMarkdown\) [Paragraph]() @@ -165,7 +165,7 @@ LocalHref generates an href for navigating to a header with the given headerText func (f *AzureDevOpsMarkdown) Paragraph(text string) (string, error) ``` -Paragraph formats a paragraph with the provided text as the contents\. +Paragraph formats a paragraph with the provided text as the contents. ### func \(\*AzureDevOpsMarkdown\) [RawHeader]() @@ -173,11 +173,11 @@ Paragraph formats a paragraph with the provided text as the contents\. func (f *AzureDevOpsMarkdown) RawHeader(level int, text string) (string, error) ``` -RawHeader converts the provided text into a header of the provided level without escaping the header text\. The level is expected to be at least 1\. +RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1. ## type [Format]() -Format is a generic interface for formatting documentation contents in a particular way\. +Format is a generic interface for formatting documentation contents in a particular way. ```go type Format interface { @@ -242,7 +242,7 @@ type Format interface { ## type [GitHubFlavoredMarkdown]() -GitHubFlavoredMarkdown provides a Format which is compatible with GitHub Flavored Markdown's syntax and semantics\. See GitHub's documentation for more details about their markdown format: https://guides.github.com/features/mastering-markdown/ +GitHubFlavoredMarkdown provides a Format which is compatible with GitHub Flavored Markdown's syntax and semantics. See GitHub's documentation for more details about their markdown format: https://guides.github.com/features/mastering-markdown/ ```go type GitHubFlavoredMarkdown struct{} @@ -254,7 +254,7 @@ type GitHubFlavoredMarkdown struct{} func (f *GitHubFlavoredMarkdown) Accordion(title, body string) (string, error) ``` -Accordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. +Accordion generates a collapsible content. The accordion's visible title while collapsed is the provided title and the expanded content is the body. ### func \(\*GitHubFlavoredMarkdown\) [AccordionHeader]() @@ -262,9 +262,9 @@ Accordion generates a collapsible content\. The accordion's visible title while func (f *GitHubFlavoredMarkdown) AccordionHeader(title string) (string, error) ``` -AccordionHeader generates the header visible when an accordion is collapsed\. +AccordionHeader generates the header visible when an accordion is collapsed. -The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently\. The result looks conceptually like the following: +The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following: ``` accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() @@ -276,7 +276,7 @@ accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + form func (f *GitHubFlavoredMarkdown) AccordionTerminator() (string, error) ``` -AccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. +AccordionTerminator generates the code necessary to terminate an accordion after the body. It is expected to be used in conjunction with AccordionHeader\(\). See AccordionHeader for a full description. ### func \(\*GitHubFlavoredMarkdown\) [Bold]() @@ -292,7 +292,7 @@ Bold converts the provided text to bold func (f *GitHubFlavoredMarkdown) CodeBlock(language, code string) (string, error) ``` -CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\. +CodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\). ### func \(\*GitHubFlavoredMarkdown\) [CodeHref]() @@ -300,7 +300,7 @@ CodeBlock wraps the provided code as a code block and tags it with the provided func (f *GitHubFlavoredMarkdown) CodeHref(loc lang.Location) (string, error) ``` -CodeHref generates an href to the provided code entry\. +CodeHref generates an href to the provided code entry. ### func \(\*GitHubFlavoredMarkdown\) [Escape]() @@ -308,7 +308,7 @@ CodeHref generates an href to the provided code entry\. func (f *GitHubFlavoredMarkdown) Escape(text string) string ``` -Escape escapes special markdown characters from the provided text\. +Escape escapes special markdown characters from the provided text. ### func \(\*GitHubFlavoredMarkdown\) [Header]() @@ -316,7 +316,7 @@ Escape escapes special markdown characters from the provided text\. func (f *GitHubFlavoredMarkdown) Header(level int, text string) (string, error) ``` -Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. +Header converts the provided text into a header of the provided level. The level is expected to be at least 1. ### func \(\*GitHubFlavoredMarkdown\) [Link]() @@ -324,7 +324,7 @@ Header converts the provided text into a header of the provided level\. The leve func (f *GitHubFlavoredMarkdown) Link(text, href string) (string, error) ``` -Link generates a link with the given text and href values\. +Link generates a link with the given text and href values. ### func \(\*GitHubFlavoredMarkdown\) [ListEntry]() @@ -332,7 +332,7 @@ Link generates a link with the given text and href values\. func (f *GitHubFlavoredMarkdown) ListEntry(depth int, text string) (string, error) ``` -ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. +ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth. A depth of 0 is considered the topmost level of list. ### func \(\*GitHubFlavoredMarkdown\) [LocalHref]() @@ -340,7 +340,7 @@ ListEntry generates an unordered list entry with the provided text at the provid func (f *GitHubFlavoredMarkdown) LocalHref(headerText string) (string, error) ``` -LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself\. +LocalHref generates an href for navigating to a header with the given headerText located within the same document as the href itself. ### func \(\*GitHubFlavoredMarkdown\) [Paragraph]() @@ -348,7 +348,7 @@ LocalHref generates an href for navigating to a header with the given headerText func (f *GitHubFlavoredMarkdown) Paragraph(text string) (string, error) ``` -Paragraph formats a paragraph with the provided text as the contents\. +Paragraph formats a paragraph with the provided text as the contents. ### func \(\*GitHubFlavoredMarkdown\) [RawHeader]() @@ -356,11 +356,11 @@ Paragraph formats a paragraph with the provided text as the contents\. func (f *GitHubFlavoredMarkdown) RawHeader(level int, text string) (string, error) ``` -RawHeader converts the provided text into a header of the provided level without escaping the header text\. The level is expected to be at least 1\. +RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1. ## type [PlainMarkdown]() -PlainMarkdown provides a Format which is compatible with the base Markdown format specification\. +PlainMarkdown provides a Format which is compatible with the base Markdown format specification. ```go type PlainMarkdown struct{} @@ -372,7 +372,7 @@ type PlainMarkdown struct{} func (f *PlainMarkdown) Accordion(title, body string) (string, error) ``` -Accordion generates a collapsible content\. Since accordions are not supported by plain markdown\, this generates a level 6 header followed by a paragraph\. +Accordion generates a collapsible content. Since accordions are not supported by plain markdown, this generates a level 6 header followed by a paragraph. ### func \(\*PlainMarkdown\) [AccordionHeader]() @@ -380,9 +380,9 @@ Accordion generates a collapsible content\. Since accordions are not supported b func (f *PlainMarkdown) AccordionHeader(title string) (string, error) ``` -AccordionHeader generates the header visible when an accordion is collapsed\. Since accordions are not supported in plain markdown\, this generates a level 6 header\. +AccordionHeader generates the header visible when an accordion is collapsed. Since accordions are not supported in plain markdown, this generates a level 6 header. -The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently\. The result looks conceptually like the following: +The AccordionHeader is expected to be used in conjunction with AccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following: ``` accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + format.AccordionTerminator() @@ -394,7 +394,7 @@ accordion := format.AccordionHeader("Accordion Title") + "Accordion Body" + form func (f *PlainMarkdown) AccordionTerminator() (string, error) ``` -AccordionTerminator generates the code necessary to terminate an accordion after the body\. Since accordions are not supported in plain markdown\, this completes a paragraph section\. It is expected to be used in conjunction with AccordionHeader\(\)\. See AccordionHeader for a full description\. +AccordionTerminator generates the code necessary to terminate an accordion after the body. Since accordions are not supported in plain markdown, this completes a paragraph section. It is expected to be used in conjunction with AccordionHeader\(\). See AccordionHeader for a full description. ### func \(\*PlainMarkdown\) [Bold]() @@ -410,7 +410,7 @@ Bold converts the provided text to bold func (f *PlainMarkdown) CodeBlock(language, code string) (string, error) ``` -CodeBlock wraps the provided code as a code block\. The provided language is ignored as it is not supported in plain markdown\. +CodeBlock wraps the provided code as a code block. The provided language is ignored as it is not supported in plain markdown. ### func \(\*PlainMarkdown\) [CodeHref]() @@ -418,7 +418,7 @@ CodeBlock wraps the provided code as a code block\. The provided language is ign func (f *PlainMarkdown) CodeHref(loc lang.Location) (string, error) ``` -CodeHref always returns the empty string\, as there is no defined file linking format in standard markdown\. +CodeHref always returns the empty string, as there is no defined file linking format in standard markdown. ### func \(\*PlainMarkdown\) [Escape]() @@ -426,7 +426,7 @@ CodeHref always returns the empty string\, as there is no defined file linking f func (f *PlainMarkdown) Escape(text string) string ``` -Escape escapes special markdown characters from the provided text\. +Escape escapes special markdown characters from the provided text. ### func \(\*PlainMarkdown\) [Header]() @@ -434,7 +434,7 @@ Escape escapes special markdown characters from the provided text\. func (f *PlainMarkdown) Header(level int, text string) (string, error) ``` -Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. +Header converts the provided text into a header of the provided level. The level is expected to be at least 1. ### func \(\*PlainMarkdown\) [Link]() @@ -442,7 +442,7 @@ Header converts the provided text into a header of the provided level\. The leve func (f *PlainMarkdown) Link(text, href string) (string, error) ``` -Link generates a link with the given text and href values\. +Link generates a link with the given text and href values. ### func \(\*PlainMarkdown\) [ListEntry]() @@ -450,7 +450,7 @@ Link generates a link with the given text and href values\. func (f *PlainMarkdown) ListEntry(depth int, text string) (string, error) ``` -ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. +ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth. A depth of 0 is considered the topmost level of list. ### func \(\*PlainMarkdown\) [LocalHref]() @@ -458,7 +458,7 @@ ListEntry generates an unordered list entry with the provided text at the provid func (f *PlainMarkdown) LocalHref(headerText string) (string, error) ``` -LocalHref always returns the empty string\, as header links are not supported in plain markdown\. +LocalHref always returns the empty string, as header links are not supported in plain markdown. ### func \(\*PlainMarkdown\) [Paragraph]() @@ -466,7 +466,7 @@ LocalHref always returns the empty string\, as header links are not supported in func (f *PlainMarkdown) Paragraph(text string) (string, error) ``` -Paragraph formats a paragraph with the provided text as the contents\. +Paragraph formats a paragraph with the provided text as the contents. ### func \(\*PlainMarkdown\) [RawHeader]() @@ -474,7 +474,7 @@ Paragraph formats a paragraph with the provided text as the contents\. func (f *PlainMarkdown) RawHeader(level int, text string) (string, error) ``` -RawHeader converts the provided text into a header of the provided level without escaping the header text\. The level is expected to be at least 1\. +RawHeader converts the provided text into a header of the provided level without escaping the header text. The level is expected to be at least 1. diff --git a/format/formatcore/README.md b/format/formatcore/README.md index be083e9..93c100d 100755 --- a/format/formatcore/README.md +++ b/format/formatcore/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/format/formatcore" ``` -Package formatcore provides utilities for creating formatters like those found in the format package\. +Package formatcore provides utilities for creating formatters like those found in the format package. ## Index @@ -38,7 +38,7 @@ Bold converts the provided text to bold func CodeBlock(code string) string ``` -CodeBlock wraps the provided code as a code block\. Language syntax highlighting is not supported\. +CodeBlock wraps the provided code as a code block. Language syntax highlighting is not supported. ## func [Escape]() @@ -46,7 +46,7 @@ CodeBlock wraps the provided code as a code block\. Language syntax highlighting func Escape(text string) string ``` -Escape escapes the special characters in the provided text\, but leaves URLs found intact\. Note that the URLs included must begin with a scheme to skip the escaping\. +Escape escapes the special characters in the provided text, but leaves URLs found intact. Note that the URLs included must begin with a scheme to skip the escaping. ## func [GFMAccordion]() @@ -54,7 +54,7 @@ Escape escapes the special characters in the provided text\, but leaves URLs fou func GFMAccordion(title, body string) string ``` -GFMAccordion generates a collapsible content\. The accordion's visible title while collapsed is the provided title and the expanded content is the body\. +GFMAccordion generates a collapsible content. The accordion's visible title while collapsed is the provided title and the expanded content is the body. ## func [GFMAccordionHeader]() @@ -62,9 +62,9 @@ GFMAccordion generates a collapsible content\. The accordion's visible title whi func GFMAccordionHeader(title string) string ``` -GFMAccordionHeader generates the header visible when an accordion is collapsed\. +GFMAccordionHeader generates the header visible when an accordion is collapsed. -The GFMAccordionHeader is expected to be used in conjunction with GFMAccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently\. The result looks conceptually like the following: +The GFMAccordionHeader is expected to be used in conjunction with GFMAccordionTerminator\(\) when the demands of the body's rendering requires it to be generated independently. The result looks conceptually like the following: ``` accordion := GFMAccordionHeader("Accordion Title") + "Accordion Body" + GFMAccordionTerminator() @@ -76,7 +76,7 @@ accordion := GFMAccordionHeader("Accordion Title") + "Accordion Body" + GFMAccor func GFMAccordionTerminator() string ``` -GFMAccordionTerminator generates the code necessary to terminate an accordion after the body\. It is expected to be used in conjunction with GFMAccordionHeader\(\)\. See GFMAccordionHeader for a full description\. +GFMAccordionTerminator generates the code necessary to terminate an accordion after the body. It is expected to be used in conjunction with GFMAccordionHeader\(\). See GFMAccordionHeader for a full description. ## func [GFMCodeBlock]() @@ -84,7 +84,7 @@ GFMAccordionTerminator generates the code necessary to terminate an accordion af func GFMCodeBlock(language, code string) string ``` -GFMCodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\)\, using the triple backtick format from GitHub Flavored Markdown\. +GFMCodeBlock wraps the provided code as a code block and tags it with the provided language \(or no language if the empty string is provided\), using the triple backtick format from GitHub Flavored Markdown. ## func [Header]() @@ -92,7 +92,7 @@ GFMCodeBlock wraps the provided code as a code block and tags it with the provid func Header(level int, text string) (string, error) ``` -Header converts the provided text into a header of the provided level\. The level is expected to be at least 1\. +Header converts the provided text into a header of the provided level. The level is expected to be at least 1. ## func [Link]() @@ -100,7 +100,7 @@ Header converts the provided text into a header of the provided level\. The leve func Link(text, href string) string ``` -Link generates a link with the given text and href values\. +Link generates a link with the given text and href values. ## func [ListEntry]() @@ -108,7 +108,7 @@ Link generates a link with the given text and href values\. func ListEntry(depth int, text string) string ``` -ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth\. A depth of 0 is considered the topmost level of list\. +ListEntry generates an unordered list entry with the provided text at the provided zero\-indexed depth. A depth of 0 is considered the topmost level of list. ## func [Paragraph]() @@ -116,7 +116,7 @@ ListEntry generates an unordered list entry with the provided text at the provid func Paragraph(text string) string ``` -Paragraph formats a paragraph with the provided text as the contents\. +Paragraph formats a paragraph with the provided text as the contents. ## func [PlainText]() @@ -124,7 +124,7 @@ Paragraph formats a paragraph with the provided text as the contents\. func PlainText(text string) string ``` -PlainText converts a markdown string to the plain text that appears in the rendered output\. +PlainText converts a markdown string to the plain text that appears in the rendered output. diff --git a/format/formatcore/base.go b/format/formatcore/base.go index 085d192..08e0f05 100644 --- a/format/formatcore/base.go +++ b/format/formatcore/base.go @@ -128,7 +128,7 @@ func Paragraph(text string) string { } var ( - specialCharacterRegex = regexp.MustCompile("([\\\\`*_{}\\[\\]()<>#+-.!~])") + specialCharacterRegex = regexp.MustCompile("([\\\\`*_{}\\[\\]()<>#+\\-!~])") urlRegex = xurls.Strict() // Require a scheme in URLs ) diff --git a/format/formatcore/base_test.go b/format/formatcore/base_test.go index 97a17ab..a00fdf9 100644 --- a/format/formatcore/base_test.go +++ b/format/formatcore/base_test.go @@ -61,8 +61,8 @@ func TestEscape(t *testing.T) { in, out string }{ { - in: "plain text", - out: `plain text`, + in: "plain, text.", + out: `plain, text.`, }, { in: "**bold** text", diff --git a/lang/README.md b/lang/README.md index 613a3f0..e684273 100644 --- a/lang/README.md +++ b/lang/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/lang" ``` -Package lang provides constructs for defining golang language constructs and extracting information from them for documentation purposes\. +Package lang provides constructs for defining golang language constructs and extracting information from them for documentation purposes. ## Index @@ -98,7 +98,7 @@ Package lang provides constructs for defining golang language constructs and ext ## type [Block]() -Block defines a single block element \(e\.g\. paragraph\, code block\) in the documentation for a symbol or package\. +Block defines a single block element \(e.g. paragraph, code block\) in the documentation for a symbol or package. ```go type Block struct { @@ -112,7 +112,7 @@ type Block struct { func NewBlock(cfg *Config, kind BlockKind, text string) *Block ``` -NewBlock creates a new block element of the provided kind and with the given text contents\. +NewBlock creates a new block element of the provided kind and with the given text contents. ### func \(\*Block\) [Kind]() @@ -120,7 +120,7 @@ NewBlock creates a new block element of the provided kind and with the given tex func (b *Block) Kind() BlockKind ``` -Kind provides the kind of data that this block's text should be interpreted as\. +Kind provides the kind of data that this block's text should be interpreted as. ### func \(\*Block\) [Level]() @@ -128,7 +128,7 @@ Kind provides the kind of data that this block's text should be interpreted as\. func (b *Block) Level() int ``` -Level provides the default level that a block of kind HeaderBlock will render at in the output\. The level is not used for other block types\. +Level provides the default level that a block of kind HeaderBlock will render at in the output. The level is not used for other block types. ### func \(\*Block\) [Text]() @@ -136,11 +136,11 @@ Level provides the default level that a block of kind HeaderBlock will render at func (b *Block) Text() string ``` -Text provides the raw text of the block's contents\. The text is pre\-scrubbed and sanitized as determined by the block's Kind\(\)\, but it is not wrapped in any special constructs for rendering purposes \(such as markdown code blocks\)\. +Text provides the raw text of the block's contents. The text is pre\-scrubbed and sanitized as determined by the block's Kind\(\), but it is not wrapped in any special constructs for rendering purposes \(such as markdown code blocks\). ## type [BlockKind]() -BlockKind identifies the type of block element represented by the corresponding Block\. +BlockKind identifies the type of block element represented by the corresponding Block. ```go type BlockKind string @@ -161,7 +161,7 @@ const ( ## type [Config]() -Config defines contextual information used to resolve documentation for a construct\. +Config defines contextual information used to resolve documentation for a construct. ```go type Config struct { @@ -180,7 +180,7 @@ type Config struct { func NewConfig(log logger.Logger, workDir string, pkgDir string, opts ...ConfigOption) (*Config, error) ``` -NewConfig generates a Config for the provided package directory\. It will resolve the filepath and attempt to determine the repository containing the directory\. If no repository is found\, the Repo field will be set to nil\. An error is returned if the provided directory is invalid\. +NewConfig generates a Config for the provided package directory. It will resolve the filepath and attempt to determine the repository containing the directory. If no repository is found, the Repo field will be set to nil. An error is returned if the provided directory is invalid. ### func \(\*Config\) [Inc]() @@ -188,11 +188,11 @@ NewConfig generates a Config for the provided package directory\. It will resolv func (c *Config) Inc(step int) *Config ``` -Inc copies the Config and increments the level by the provided step\. +Inc copies the Config and increments the level by the provided step. ## type [ConfigOption]() -ConfigOption modifies the Config generated by NewConfig\. +ConfigOption modifies the Config generated by NewConfig. ```go type ConfigOption func(c *Config) error @@ -204,11 +204,11 @@ type ConfigOption func(c *Config) error func ConfigWithRepoOverrides(overrides *Repo) ConfigOption ``` -ConfigWithRepoOverrides defines a set of manual overrides for the repository information to be used in place of automatic repository detection\. +ConfigWithRepoOverrides defines a set of manual overrides for the repository information to be used in place of automatic repository detection. ## type [Doc]() -Doc provides access to the documentation comment contents for a package or symbol in a structured form\. +Doc provides access to the documentation comment contents for a package or symbol in a structured form. ```go type Doc struct { @@ -222,7 +222,7 @@ type Doc struct { func NewDoc(cfg *Config, text string) *Doc ``` -NewDoc initializes a Doc struct from the provided raw documentation text and with headers rendered by default at the heading level provided\. Documentation is separated into block level elements using the standard rules from golang's documentation conventions\. +NewDoc initializes a Doc struct from the provided raw documentation text and with headers rendered by default at the heading level provided. Documentation is separated into block level elements using the standard rules from golang's documentation conventions. ### func \(\*Doc\) [Blocks]() @@ -230,7 +230,7 @@ NewDoc initializes a Doc struct from the provided raw documentation text and wit func (d *Doc) Blocks() []*Block ``` -Blocks holds the list of block elements that makes up the documentation contents\. +Blocks holds the list of block elements that makes up the documentation contents. ### func \(\*Doc\) [Level]() @@ -242,7 +242,7 @@ Level provides the default level that headers within the documentation should be ## type [Example]() -Example holds a single documentation example for a package or symbol\. +Example holds a single documentation example for a package or symbol. ```go type Example struct { @@ -256,7 +256,7 @@ type Example struct { func NewExample(cfg *Config, name string, doc *doc.Example) *Example ``` -NewExample creates a new example from the example function's name\, its documentation example and the files holding code related to the example\. +NewExample creates a new example from the example function's name, its documentation example and the files holding code related to the example. ### func \(\*Example\) [Code]() @@ -264,7 +264,7 @@ NewExample creates a new example from the example function's name\, its document func (ex *Example) Code() (string, error) ``` -Code provides the raw text code representation of the example's contents\. +Code provides the raw text code representation of the example's contents. ### func \(\*Example\) [Doc]() @@ -272,7 +272,7 @@ Code provides the raw text code representation of the example's contents\. func (ex *Example) Doc() *Doc ``` -Doc provides the structured contents of the documentation comment for the example\. +Doc provides the structured contents of the documentation comment for the example. ### func \(\*Example\) [HasOutput]() @@ -280,7 +280,7 @@ Doc provides the structured contents of the documentation comment for the exampl func (ex *Example) HasOutput() bool ``` -HasOutput indicates whether the example contains any example output\. +HasOutput indicates whether the example contains any example output. ### func \(\*Example\) [Level]() @@ -288,7 +288,7 @@ HasOutput indicates whether the example contains any example output\. func (ex *Example) Level() int ``` -Level provides the default level that headers for the example should be rendered\. +Level provides the default level that headers for the example should be rendered. ### func \(\*Example\) [Location]() @@ -296,7 +296,7 @@ Level provides the default level that headers for the example should be rendered func (ex *Example) Location() Location ``` -Location returns a representation of the node's location in a file within a repository\. +Location returns a representation of the node's location in a file within a repository. ### func \(\*Example\) [Name]() @@ -304,7 +304,7 @@ Location returns a representation of the node's location in a file within a repo func (ex *Example) Name() string ``` -Name provides a pretty\-printed name for the specific example\, if one was provided\. +Name provides a pretty\-printed name for the specific example, if one was provided. ### func \(\*Example\) [Output]() @@ -312,7 +312,7 @@ Name provides a pretty\-printed name for the specific example\, if one was provi func (ex *Example) Output() string ``` -Output provides the code's example output\. +Output provides the code's example output. ### func \(\*Example\) [Summary]() @@ -320,7 +320,7 @@ Output provides the code's example output\. func (ex *Example) Summary() string ``` -Summary provides the one\-sentence summary of the example's documentation comment\. +Summary provides the one\-sentence summary of the example's documentation comment. ### func \(\*Example\) [Title]() @@ -328,11 +328,11 @@ Summary provides the one\-sentence summary of the example's documentation commen func (ex *Example) Title() string ``` -Title provides a formatted string to print as the title of the example\. It incorporates the example's name\, if present\. +Title provides a formatted string to print as the title of the example. It incorporates the example's name, if present. ## type [File]() -File holds information for rendering a single file that contains one or more packages\. +File holds information for rendering a single file that contains one or more packages. ```go type File struct { @@ -348,11 +348,11 @@ type File struct { func NewFile(header, footer string, packages []*Package) *File ``` -NewFile creates a new instance of File with the provided information\. +NewFile creates a new instance of File with the provided information. ## type [Func]() -Func holds documentation information for a single func declaration within a package or type\. +Func holds documentation information for a single func declaration within a package or type. ```go type Func struct { @@ -366,7 +366,7 @@ type Func struct { func NewFunc(cfg *Config, doc *doc.Func, examples []*doc.Example) *Func ``` -NewFunc creates a new Func from the corresponding documentation construct from the standard library\, the related token\.FileSet for the package and the list of examples for the package\. +NewFunc creates a new Func from the corresponding documentation construct from the standard library, the related token.FileSet for the package and the list of examples for the package. ### func \(\*Func\) [Doc]() @@ -374,7 +374,7 @@ NewFunc creates a new Func from the corresponding documentation construct from t func (fn *Func) Doc() *Doc ``` -Doc provides the structured contents of the documentation comment for the function\. +Doc provides the structured contents of the documentation comment for the function. ### func \(\*Func\) [Examples]() @@ -382,7 +382,7 @@ Doc provides the structured contents of the documentation comment for the functi func (fn *Func) Examples() (examples []*Example) ``` -Examples provides the list of examples from the list given on initialization that pertain to the function\. +Examples provides the list of examples from the list given on initialization that pertain to the function. ### func \(\*Func\) [Level]() @@ -390,7 +390,7 @@ Examples provides the list of examples from the list given on initialization tha func (fn *Func) Level() int ``` -Level provides the default level at which headers for the func should be rendered in the final documentation\. +Level provides the default level at which headers for the func should be rendered in the final documentation. ### func \(\*Func\) [Location]() @@ -398,7 +398,7 @@ Level provides the default level at which headers for the func should be rendere func (fn *Func) Location() Location ``` -Location returns a representation of the node's location in a file within a repository\. +Location returns a representation of the node's location in a file within a repository. ### func \(\*Func\) [Name]() @@ -406,7 +406,7 @@ Location returns a representation of the node's location in a file within a repo func (fn *Func) Name() string ``` -Name provides the name of the function\. +Name provides the name of the function. ### func \(\*Func\) [Receiver]() @@ -414,7 +414,7 @@ Name provides the name of the function\. func (fn *Func) Receiver() string ``` -Receiver provides the type of the receiver for the function\, or empty string if there is no receiver type\. +Receiver provides the type of the receiver for the function, or empty string if there is no receiver type. ### func \(\*Func\) [Signature]() @@ -422,7 +422,7 @@ Receiver provides the type of the receiver for the function\, or empty string if func (fn *Func) Signature() (string, error) ``` -Signature provides the raw text representation of the code for the function's signature\. +Signature provides the raw text representation of the code for the function's signature. ### func \(\*Func\) [Summary]() @@ -438,11 +438,11 @@ Summary provides the one\-sentence summary of the function's documentation comme func (fn *Func) Title() string ``` -Title provides the formatted name of the func\. It is primarily designed for generating headers\. +Title provides the formatted name of the func. It is primarily designed for generating headers. ## type [Location]() -Location holds information for identifying a position within a file and repository\, if present\. +Location holds information for identifying a position within a file and repository, if present. ```go type Location struct { @@ -460,11 +460,11 @@ type Location struct { func NewLocation(cfg *Config, node ast.Node) Location ``` -NewLocation returns a location for the provided Config and ast\.Node combination\. This is typically not called directly\, but is made available via the Location\(\) methods of various lang constructs\. +NewLocation returns a location for the provided Config and ast.Node combination. This is typically not called directly, but is made available via the Location\(\) methods of various lang constructs. ## type [Package]() -Package holds documentation information for a package and all of the symbols contained within it\. +Package holds documentation information for a package and all of the symbols contained within it. ```go type Package struct { @@ -478,7 +478,7 @@ type Package struct { func NewPackage(cfg *Config, doc *doc.Package, examples []*doc.Example) *Package ``` -NewPackage creates a representation of a package's documentation from the raw documentation constructs provided by the standard library\. This is only recommended for advanced scenarios\. Most consumers will find it easier to use NewPackageFromBuild instead\. +NewPackage creates a representation of a package's documentation from the raw documentation constructs provided by the standard library. This is only recommended for advanced scenarios. Most consumers will find it easier to use NewPackageFromBuild instead. ### func [NewPackageFromBuild]() @@ -486,7 +486,7 @@ NewPackage creates a representation of a package's documentation from the raw do func NewPackageFromBuild(log logger.Logger, pkg *build.Package, opts ...PackageOption) (*Package, error) ``` -NewPackageFromBuild creates a representation of a package's documentation from the build metadata for that package\. It can be configured using the provided options\. +NewPackageFromBuild creates a representation of a package's documentation from the build metadata for that package. It can be configured using the provided options. ### func \(\*Package\) [Consts]() @@ -494,7 +494,7 @@ NewPackageFromBuild creates a representation of a package's documentation from t func (pkg *Package) Consts() (consts []*Value) ``` -Consts lists the top\-level constants provided by the package\. +Consts lists the top\-level constants provided by the package. ### func \(\*Package\) [Dir]() @@ -502,7 +502,7 @@ Consts lists the top\-level constants provided by the package\. func (pkg *Package) Dir() string ``` -Dir provides the name of the full directory in which the package is located\. +Dir provides the name of the full directory in which the package is located. ### func \(\*Package\) [Dirname]() @@ -510,7 +510,7 @@ Dir provides the name of the full directory in which the package is located\. func (pkg *Package) Dirname() string ``` -Dirname provides the name of the leaf directory in which the package is located\. +Dirname provides the name of the leaf directory in which the package is located. ### func \(\*Package\) [Doc]() @@ -518,7 +518,7 @@ Dirname provides the name of the leaf directory in which the package is located\ func (pkg *Package) Doc() *Doc ``` -Doc provides the structured contents of the documentation comment for the package\. +Doc provides the structured contents of the documentation comment for the package. ### func \(\*Package\) [Examples]() @@ -526,7 +526,7 @@ Doc provides the structured contents of the documentation comment for the packag func (pkg *Package) Examples() (examples []*Example) ``` -Examples provides the package\-level examples that have been defined\. This does not include examples that are associated with symbols contained within the package\. +Examples provides the package\-level examples that have been defined. This does not include examples that are associated with symbols contained within the package. ### func \(\*Package\) [Funcs]() @@ -534,7 +534,7 @@ Examples provides the package\-level examples that have been defined\. This does func (pkg *Package) Funcs() (funcs []*Func) ``` -Funcs lists the top\-level functions provided by the package\. +Funcs lists the top\-level functions provided by the package. ### func \(\*Package\) [Import]() @@ -542,7 +542,7 @@ Funcs lists the top\-level functions provided by the package\. func (pkg *Package) Import() string ``` -Import provides the raw text for the import declaration that is used to import code from the package\. If your package's documentation is generated from a local path and does not use Go Modules\, this will typically print \`import "\."\`\. +Import provides the raw text for the import declaration that is used to import code from the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print \`import "."\`. ### func \(\*Package\) [ImportPath]() @@ -550,7 +550,7 @@ Import provides the raw text for the import declaration that is used to import c func (pkg *Package) ImportPath() string ``` -ImportPath provides the identifier used for the package when installing or importing the package\. If your package's documentation is generated from a local path and does not use Go Modules\, this will typically print \`\.\`\. +ImportPath provides the identifier used for the package when installing or importing the package. If your package's documentation is generated from a local path and does not use Go Modules, this will typically print \`.\`. ### func \(\*Package\) [Level]() @@ -558,7 +558,7 @@ ImportPath provides the identifier used for the package when installing or impor func (pkg *Package) Level() int ``` -Level provides the default level that headers for the package's root documentation should be rendered\. +Level provides the default level that headers for the package's root documentation should be rendered. ### func \(\*Package\) [Name]() @@ -566,7 +566,7 @@ Level provides the default level that headers for the package's root documentati func (pkg *Package) Name() string ``` -Name provides the name of the package as it would be seen from another package importing it\. +Name provides the name of the package as it would be seen from another package importing it. ### func \(\*Package\) [Summary]() @@ -574,7 +574,7 @@ Name provides the name of the package as it would be seen from another package i func (pkg *Package) Summary() string ``` -Summary provides the one\-sentence summary of the package's documentation comment\. +Summary provides the one\-sentence summary of the package's documentation comment. ### func \(\*Package\) [Types]() @@ -582,7 +582,7 @@ Summary provides the one\-sentence summary of the package's documentation commen func (pkg *Package) Types() (types []*Type) ``` -Types lists the top\-level types provided by the package\. +Types lists the top\-level types provided by the package. ### func \(\*Package\) [Vars]() @@ -590,11 +590,11 @@ Types lists the top\-level types provided by the package\. func (pkg *Package) Vars() (vars []*Value) ``` -Vars lists the top\-level variables provided by the package\. +Vars lists the top\-level variables provided by the package. ## type [PackageOption]() -PackageOption configures one or more options for the package\. +PackageOption configures one or more options for the package. ```go type PackageOption func(opts *PackageOptions) error @@ -606,7 +606,7 @@ type PackageOption func(opts *PackageOptions) error func PackageWithRepositoryOverrides(repo *Repo) PackageOption ``` -PackageWithRepositoryOverrides can be used along with the NewPackageFromBuild function to define manual overrides to the automatic repository detection logic\. +PackageWithRepositoryOverrides can be used along with the NewPackageFromBuild function to define manual overrides to the automatic repository detection logic. ### func [PackageWithUnexportedIncluded]() @@ -614,11 +614,11 @@ PackageWithRepositoryOverrides can be used along with the NewPackageFromBuild fu func PackageWithUnexportedIncluded() PackageOption ``` -PackageWithUnexportedIncluded can be used along with the NewPackageFromBuild function to specify that all symbols\, including unexported ones\, should be included in the documentation for the package\. +PackageWithUnexportedIncluded can be used along with the NewPackageFromBuild function to specify that all symbols, including unexported ones, should be included in the documentation for the package. ## type [PackageOptions]() -PackageOptions holds options related to the configuration of the package and its documentation on creation\. +PackageOptions holds options related to the configuration of the package and its documentation on creation. ```go type PackageOptions struct { @@ -628,7 +628,7 @@ type PackageOptions struct { ## type [Position]() -Position represents a line and column number within a file\. +Position represents a line and column number within a file. ```go type Position struct { @@ -639,7 +639,7 @@ type Position struct { ## type [Repo]() -Repo represents information about a repository relevant to documentation generation\. +Repo represents information about a repository relevant to documentation generation. ```go type Repo struct { @@ -651,7 +651,7 @@ type Repo struct { ## type [Type]() -Type holds documentation information for a type declaration\. +Type holds documentation information for a type declaration. ```go type Type struct { @@ -665,7 +665,7 @@ type Type struct { func NewType(cfg *Config, doc *doc.Type, examples []*doc.Example) *Type ``` -NewType creates a Type from the raw documentation representation of the type\, the token\.FileSet for the package's files and the full list of examples from the containing package\. +NewType creates a Type from the raw documentation representation of the type, the token.FileSet for the package's files and the full list of examples from the containing package. ### func \(\*Type\) [Consts]() @@ -673,7 +673,7 @@ NewType creates a Type from the raw documentation representation of the type\, t func (typ *Type) Consts() []*Value ``` -Consts lists the const declaration blocks containing values of this type\. +Consts lists the const declaration blocks containing values of this type. ### func \(\*Type\) [Decl]() @@ -681,7 +681,7 @@ Consts lists the const declaration blocks containing values of this type\. func (typ *Type) Decl() (string, error) ``` -Decl provides the raw text representation of the code for the type's declaration\. +Decl provides the raw text representation of the code for the type's declaration. ### func \(\*Type\) [Doc]() @@ -689,7 +689,7 @@ Decl provides the raw text representation of the code for the type's declaration func (typ *Type) Doc() *Doc ``` -Doc provides the structured contents of the documentation comment for the type\. +Doc provides the structured contents of the documentation comment for the type. ### func \(\*Type\) [Examples]() @@ -697,7 +697,7 @@ Doc provides the structured contents of the documentation comment for the type\. func (typ *Type) Examples() (examples []*Example) ``` -Examples lists the examples pertaining to the type from the set provided on initialization\. +Examples lists the examples pertaining to the type from the set provided on initialization. ### func \(\*Type\) [Funcs]() @@ -705,7 +705,7 @@ Examples lists the examples pertaining to the type from the set provided on init func (typ *Type) Funcs() []*Func ``` -Funcs lists the funcs related to the type\. This only includes functions which return an instance of the type or its pointer\. +Funcs lists the funcs related to the type. This only includes functions which return an instance of the type or its pointer. ### func \(\*Type\) [Level]() @@ -713,7 +713,7 @@ Funcs lists the funcs related to the type\. This only includes functions which r func (typ *Type) Level() int ``` -Level provides the default level that headers for the type should be rendered\. +Level provides the default level that headers for the type should be rendered. ### func \(\*Type\) [Location]() @@ -721,7 +721,7 @@ Level provides the default level that headers for the type should be rendered\. func (typ *Type) Location() Location ``` -Location returns a representation of the node's location in a file within a repository\. +Location returns a representation of the node's location in a file within a repository. ### func \(\*Type\) [Methods]() @@ -729,7 +729,7 @@ Location returns a representation of the node's location in a file within a repo func (typ *Type) Methods() []*Func ``` -Methods lists the funcs that use the type as a value or pointer receiver\. +Methods lists the funcs that use the type as a value or pointer receiver. ### func \(\*Type\) [Name]() @@ -745,7 +745,7 @@ Name provides the name of the type func (typ *Type) Summary() string ``` -Summary provides the one\-sentence summary of the type's documentation comment\. +Summary provides the one\-sentence summary of the type's documentation comment. ### func \(\*Type\) [Title]() @@ -753,7 +753,7 @@ Summary provides the one\-sentence summary of the type's documentation comment\. func (typ *Type) Title() string ``` -Title provides a formatted name suitable for use in a header identifying the type\. +Title provides a formatted name suitable for use in a header identifying the type. ### func \(\*Type\) [Vars]() @@ -761,11 +761,11 @@ Title provides a formatted name suitable for use in a header identifying the typ func (typ *Type) Vars() []*Value ``` -Vars lists the var declaration blocks containing values of this type\. +Vars lists the var declaration blocks containing values of this type. ## type [Value]() -Value holds documentation for a var or const declaration within a package\. +Value holds documentation for a var or const declaration within a package. ```go type Value struct { @@ -779,7 +779,7 @@ type Value struct { func NewValue(cfg *Config, doc *doc.Value) *Value ``` -NewValue creates a new Value from the raw const or var documentation and the token\.FileSet of files for the containing package\. +NewValue creates a new Value from the raw const or var documentation and the token.FileSet of files for the containing package. ### func \(\*Value\) [Decl]() @@ -787,7 +787,7 @@ NewValue creates a new Value from the raw const or var documentation and the tok func (v *Value) Decl() (string, error) ``` -Decl provides the raw text representation of the code for declaring the const or var\. +Decl provides the raw text representation of the code for declaring the const or var. ### func \(\*Value\) [Doc]() @@ -795,7 +795,7 @@ Decl provides the raw text representation of the code for declaring the const or func (v *Value) Doc() *Doc ``` -Doc provides the structured contents of the documentation comment for the example\. +Doc provides the structured contents of the documentation comment for the example. ### func \(\*Value\) [Level]() @@ -803,7 +803,7 @@ Doc provides the structured contents of the documentation comment for the exampl func (v *Value) Level() int ``` -Level provides the default level that headers for the value should be rendered\. +Level provides the default level that headers for the value should be rendered. ### func \(\*Value\) [Location]() @@ -811,7 +811,7 @@ Level provides the default level that headers for the value should be rendered\. func (v *Value) Location() Location ``` -Location returns a representation of the node's location in a file within a repository\. +Location returns a representation of the node's location in a file within a repository. ### func \(\*Value\) [Summary]() @@ -819,7 +819,7 @@ Location returns a representation of the node's location in a file within a repo func (v *Value) Summary() string ``` -Summary provides the one\-sentence summary of the value's documentation comment\. +Summary provides the one\-sentence summary of the value's documentation comment. diff --git a/testData/embed/README.md b/testData/embed/README.md index 73aeb77..49c5142 100644 --- a/testData/embed/README.md +++ b/testData/embed/README.md @@ -10,7 +10,7 @@ This is content before the embed import "github.com/princjef/gomarkdoc/testData/embed" ``` -Package embed tests out embedding of documentation in an existing readme\. +Package embed tests out embedding of documentation in an existing readme. ## Index @@ -23,7 +23,7 @@ Package embed tests out embedding of documentation in an existing readme\. func EmbeddedFunc(param int) int ``` -EmbeddedFunc is present in embedded content\. +EmbeddedFunc is present in embedded content. @@ -44,7 +44,7 @@ This is content after the embed import "github.com/princjef/gomarkdoc/testData/embed" ``` -Package embed tests out embedding of documentation in an existing readme\. +Package embed tests out embedding of documentation in an existing readme. ## Index @@ -57,7 +57,7 @@ Package embed tests out embedding of documentation in an existing readme\. func EmbeddedFunc(param int) int ``` -EmbeddedFunc is present in embedded content\. +EmbeddedFunc is present in embedded content. @@ -78,7 +78,7 @@ This is content after the second embed import "github.com/princjef/gomarkdoc/testData/embed" ``` -Package embed tests out embedding of documentation in an existing readme\. +Package embed tests out embedding of documentation in an existing readme. ## Index @@ -91,7 +91,7 @@ Package embed tests out embedding of documentation in an existing readme\. func EmbeddedFunc(param int) int ``` -EmbeddedFunc is present in embedded content\. +EmbeddedFunc is present in embedded content. diff --git a/testData/nested/README.md b/testData/nested/README.md index 78a5cf4..e4ead36 100755 --- a/testData/nested/README.md +++ b/testData/nested/README.md @@ -17,7 +17,7 @@ import "github.com/princjef/gomarkdoc/testData/nested" func Parent() int ``` -Parent is in the parent package\. +Parent is in the parent package. diff --git a/testData/nested/inner/README.md b/testData/nested/inner/README.md index 7f9c5e3..03227ae 100755 --- a/testData/nested/inner/README.md +++ b/testData/nested/inner/README.md @@ -17,7 +17,7 @@ import "github.com/princjef/gomarkdoc/testData/nested/inner" func Child() int ``` -Child is in the child package\. +Child is in the child package. diff --git a/testData/simple/README.md b/testData/simple/README.md index 66dec70..7bec561 100755 --- a/testData/simple/README.md +++ b/testData/simple/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/testData/simple" ``` -Package simple contains some simple code to exercise basic scenarios for documentation purposes\. +Package simple contains, some simple code to exercise basic scenarios for documentation purposes. ## Index @@ -17,9 +17,9 @@ Package simple contains some simple code to exercise basic scenarios for documen ## type [Num]() -Num is a number\. +Num is a number. -It is just a test type so that we can make sure this works\. +It is just a test type so that we can make sure this works. ```go type Num int @@ -31,7 +31,7 @@ type Num int func AddNums(num1, num2 Num) Num ``` -AddNums adds two Nums together\. +AddNums adds two Nums together. ### func \(Num\) [Add]() @@ -39,7 +39,7 @@ AddNums adds two Nums together\. func (n Num) Add(num Num) Num ``` -Add adds the other num to this one\. +Add adds the other num to this one. diff --git a/testData/simple/main.go b/testData/simple/main.go index 3cceff4..f1d8f26 100644 --- a/testData/simple/main.go +++ b/testData/simple/main.go @@ -1,4 +1,4 @@ -// Package simple contains some simple code to exercise basic scenarios +// Package simple contains, some simple code to exercise basic scenarios // for documentation purposes. package simple diff --git a/testData/tags/README.md b/testData/tags/README.md index a48fcd6..846cfe3 100755 --- a/testData/tags/README.md +++ b/testData/tags/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/testData/tags" ``` -Package tags contains code to demonstrate usage of build tags\. +Package tags contains code to demonstrate usage of build tags. ## Index @@ -20,7 +20,7 @@ Package tags contains code to demonstrate usage of build tags\. func Tagged() int ``` -Tagged is only visible with tags\. +Tagged is only visible with tags. ## func [Untagged]() @@ -28,7 +28,7 @@ Tagged is only visible with tags\. func Untagged() int ``` -Untagged is visible without tags\. +Untagged is visible without tags. diff --git a/testData/unexported/README.md b/testData/unexported/README.md index ebaa29b..26cc61f 100755 --- a/testData/unexported/README.md +++ b/testData/unexported/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/testData/unexported" ``` -Package unexported contains some simple code to exercise basic scenarios for documentation purposes\. +Package unexported contains some simple code to exercise basic scenarios for documentation purposes. ## Index @@ -18,9 +18,9 @@ Package unexported contains some simple code to exercise basic scenarios for doc ## type [Num]() -Num is a number\. +Num is a number. -It is just a test type so that we can make sure this works\. +It is just a test type so that we can make sure this works. ```go type Num int @@ -32,7 +32,7 @@ type Num int func AddNums(num1, num2 Num) Num ``` -AddNums adds two Nums together\. +AddNums adds two Nums together. ### func [addInternal]() @@ -40,7 +40,7 @@ AddNums adds two Nums together\. func addInternal(num1, num2 Num) Num ``` -addInternal is a private version of AddNums\. +addInternal is a private version of AddNums. ### func \(Num\) [Add]() @@ -48,7 +48,7 @@ addInternal is a private version of AddNums\. func (n Num) Add(num Num) Num ``` -Add adds the other num to this one\. +Add adds the other num to this one. diff --git a/testData/untagged/README.md b/testData/untagged/README.md index 3c31f16..20410fd 100755 --- a/testData/untagged/README.md +++ b/testData/untagged/README.md @@ -6,7 +6,7 @@ import "github.com/princjef/gomarkdoc/testData/untagged" ``` -Package untagged contains code to demonstrate usage of build tags\. +Package untagged contains code to demonstrate usage of build tags. ## Index @@ -19,7 +19,7 @@ Package untagged contains code to demonstrate usage of build tags\. func Untagged() int ``` -Untagged is visible without tags\. +Untagged is visible without tags.