Source Code Documentation in AsciiDoc

Layout

  • The document title is the name of the module (=).

  • The 1st level section title is the function or method name (==).

  • A source block containing the function signature with a block title containing the file path.

  • Underneath the function signature, add a description of what it does. Add [NOTICE], [WARNING], or other annotations wherever necessary.

  • Sections like Parameters, Returns, and Example are all in bold with a colon at the end (e.g. Parameters:).

  • The example itself is in a source code block ([source]).

Example

= UUID

== NewUUID

.graph/uuid.go
[source,go]
--
func NewUUID() UUID
--

Creates a new random-based universally unique identifier (see RFC 9562: UUID version 4).

== ToUUID

.graph/uuid.go
[source,go]
--
func ToUUID(s string) (UUID, error)
--

*Parameters:*

* _s_:
A UUID string representation (`aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee`).
It doesn't matter if the UUID is random-, time- or hash-based,
as long as it is in the expected format.

*Returns:*

* On success, returns the UUID represented by the input string.
* An error if the UUID string cannot be parsed.

*Example:*

[source,go]
--
uuid, err := ToUUID("5e2a0a65-1b33-44fa-8ba2-947f83b16be6")
if err != nil {
    panic(err)
}

fmt.Println("Success!")
--

== UUID.ToString

.graph/uuid.go
[source,go]
--
func (u UUID) ToString() string
--

Converts the UUID to its string representation.

*Returns:*

* A string representation of _u_.

*Example:*

[source,go]
--
uuid := NewUUID()
fmt.Println(uuid.ToString()) // 5e2a0a65-1b33-44fa-8ba2-947f83b16be6
--