Source Code Documentation in AsciiDoc

Layout

  • h1 header is the name of the module

  • h2 header is the name of the function

  • source block with a block title containing the function signature and the file, where it is defined respectively

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

  • The example itself is in a source code block

Example

= Package `uuid`

== Types

=== UUID

.graph/uuid.go
[source,go]
--
type UUID [16]byte
--

== Functions

=== NewUUID

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

Creates a new random-based universally unique identifier (UUID).

=== 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-based, time-based or hash-based,
as long as it is in the expected format.

*Returns:*

* On success, returns an equivalent UUID from the UUID string representation.

* An error, if the UUID string representation 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
--

Convert the UUID into its string representation.

*Returns:*

* A string representation of _u_.

*Examples:*

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

=== UUID.MarshalJSON

.graph/uuid.go
[source,go]
--
func (u UUID) MarshalJSON() ([]byte, error)
--

=== UUID.UnmarshalJSON

.graph/uuid.go
[source,go]
--
func (u *UUID) UnmarshalJSON(data []byte) error
--