diff --git a/docs/doc-comments-prompt.txt b/docs/doc-comments-prompt.txt new file mode 100644 index 0000000..d283c09 --- /dev/null +++ b/docs/doc-comments-prompt.txt @@ -0,0 +1,59 @@ +Always start documentation comments with the symbol name verbatim, and then use this to start a sentence summarizing the symbol's function + +For documentation comments on functions and methods: + +- Write a general description in one or two sentences at the top + +- use the format `# Header` for headings of sections. + +- Follow by a description of the parameters and then return values, with a series of bullet points describing each item, each with an empty line in between. + +- Last, describe the expected behaviour of the function or method, keep this with one space apart from the comment start token + +For documentation on types, variables and comments, write 1-2 sentences describing how the item is used. + +For documentation on package, summarise in up to 3 sentences the functions and purpose of the package + +Do not use markdown ** or __ or any similar things in initial words of a bullet point, instead use standard godoc style # prefix for header sections + +ALWAYS separate each bullet point with an empty line, and ALWAYS indent them three spaces after the // + +NEVER put a colon after the first word of the first line of a document comment + +Use British English spelling and Oxford commas + +Always break lines before 80 columns, and flow under bullet points two columns right of the bullet point hyphen. + +Do not write a section for parameters or return values when there is none + +In the `# Expected behavior` section always add an empty line after this title before the description, and don't indent this section as this makes it appear as preformatted monospace. + +A good typical example: + +// NewServer initializes and returns a new Server instance based on the provided +// ServerParams and optional settings. It sets up storage, initializes the +// relay, and configures necessary components for server operation. +// +// # Parameters +// +// - sp (*ServerParams): The configuration parameters for initializing the +// server. +// +// - opts (...options.O): Optional settings that modify the server's behavior. +// +// # Return Values +// +// - s (*Server): The newly created Server instance. +// +// - err (error): An error if any step fails during initialization. +// +// # Expected Behaviour +// +// - Initializes storage with the provided database path. +// +// - Configures the server's options using the default settings and applies any +// optional settings provided. +// +// - Sets up a ServeMux for handling HTTP requests. +// +// - Initializes the relay, starting its operation in a separate goroutine. diff --git a/docs/orly.png b/docs/orly.png new file mode 100644 index 0000000..285b9d2 Binary files /dev/null and b/docs/orly.png differ diff --git a/readme.adoc b/readme.adoc index 7923e2a..83bd84e 100644 --- a/readme.adoc +++ b/readme.adoc @@ -2,6 +2,8 @@ :toc: :note-caption: note 👉 +image:./docs/orly.png[orly.dev] + image:https://img.shields.io/badge/godoc-documentation-blue.svg[Documentation,link=https://pkg.go.dev/next.orly.dev] image:https://img.shields.io/badge/donate-geyser_crowdfunding_project_page-orange.svg[Support this project,link=https://geyser.fund/project/orly] zap me: ⚡️mlekudev@getalby.com