SlothCreator: Building Documentation with Gungnir in Odin

Build Gungnir documentation for an Odin project that contains a DocG Catalog.

Overview

This sample code project was based on Apple’s Sloth Creator (MIT).

Note

The original SlothCreator sample code project is associated with the WWDC21 sessions:

Is recommended to check them to learn more about Swift’s DocC, main inspiration for Gungnir.

Configure the Sample Code Project

To build documentation for this package, use Gungnir, go to the project root (where project.odin file is located) and execute the following command:

$ gungnir .

## Overview

SlothCreator provides models and utilities for creating, tracking, and caring for sloths. The framework provides structures to model an individual Sloth, and identify them by key characteristics, including their Sloth/name and special supernatural Sloth/power. You can create your own custom sloths using a SlothGenerator, and name them using a NameGenerator.

Sloths need careful feeding and maintenance to ensure their health and happiness. You maintain their Sloth/energyLevel by providing the correct Sloth/Food and a suitable Habitat. You can exercise your sloth by providing a fun or restful Activity.

Featured

Topics

Getting Started

Getting Started

Topics

Files

Enumerations

Structs

Constants

🅲 SlothFood

Procedures

Topics

Enumerations

🅴 Speed

Topics

Enumerations

🅴 SlothFoodEnum

Structs

🆂 Food

Constants

🅲 SlothFood

Procedures

🅿 init_food/2

Declaration

Color :: enum

Values

Green

The color green.

Declaration

Green

Yellow

The color yellow.

Declaration

Yellow

Orange

The color orange.

Declaration

Orange

Blue

The color blue.

Declaration

Blue

See Also

color

Declaration

Power :: enum

Values

Ice

The ice power.

Ice sloths thrive below freezing temperatures. Their claws have the power of summoning snow and ice. Despite their usual slowness, their metabolism has the ability of speeding up for snowball fights.

Declaration

Ice

Fire

The fire power.

Fire sloths thrive at boiling temperatures. Their claws have the power of summoning fire. A fire sloth is happiest while taking a lava bath.

Declaration

Fire

Wind

The wind power.

Wind sloths thrive at soaring altitudes. Their claws have the power of summoning wind, propelling their furry bodies through the air in a motion similar to flying. The high speed of the wind causes the sloths’ fur to be in perpetual disarray.

Declaration

Wind

Lightning

The lightning power.

Lightning sloths thrive in stormy climates. Their claws have the power of summoning lightning. Beware of shaking a lightning sloth’s hand without rubber shoes.

Declaration

Lightning

None

No special power.

Standard sloths are still extraordinary creatures. Their claws have the power of holding onto tree branches, rocky outcrops, and outstretched arms. They might be slow, but they are still magnificent.

Declaration

None

See Also

power

Speeds

Slow
Medium
Fast
Supersonic

Comparing Speeds

odin:docs/overview/#comparison-operators

Declaration

Speed :: enum

Values

Slow

Moves slightly faster than a snail.

Declaration

Slow

Medium

Moves at an average speed.

Declaration

Medium

Fast

Moves faster than a hare.

Declaration

Fast

Supersonic

Moves faster than the speed of sound.

Declaration

Supersonic

See Also

speed

Declaration

SlothFoodEnum :: enum

Values

Green

A spindly stick.

Declaration

Twig

Twig

A regular-sized leaf.

Declaration

Twig

Regular_Leaf

A regular-sized leaf.

Declaration

Regular_Leaf

Large_Leaf

A large leaf.

Declaration

Large_Leaf

See Also

Declaration

Schedule :: struct

Values

events

The actions a sloth performs at scheduled times.

Declaration

events: map[int]Event

See Also

Struct

`Food`

Food that a sloth can consume.

Sloths love to eat the leaves and twigs they find in the rainforest canopy as they slowly move around. To feed them these items, you can use the Twig, Regular_Leaf and Large_Leaf default foods.

Sloth.sloth_eat(sloth, Sloth.SlothFoodEnum.Large_Leaf)

You can also define your own custom sloth food by providing a name and the energy level. When the sloth eats your custom food, their energy level increases by the energy of the food:

flower := Food{name = "Flower Bud", energy = 10}
Sloth.sloth_eat(sloth, flower)

Declaration

Food :: struct

Values

name

The name of the food.

Declaration

name: string

energy

The amount of energy the food contains.

When sloths metabolize the food they eat, their Sloth/energy_level increases by the amount of energy the food contains.

Declaration

energy: int

See Also

Struct

`Habitat`

The habitat where sloths live.

Sloths love hanging out in rain forests, and are especially grateful for hot and humid habitats.

They spend much of their time asleep, so make sure the habitats you create provide comfortable and reliable branches in a large number of trees for them to feel safe and protected.

The warmth and humidity of the habitat affect how much a sloth’s Sloth/energy_level increases when they sleep:


lovely_habitat := Habitat{is_humid = true, is_warm = true}

cold_dry_habitat := Habitat{is_humid = false, is_warm = false}

sloth_sleep(warm_sloth, lovely_habitat)

sloth_sleep(icy_sloth, cold_dry_habitat, number_of_hours = 22)

Declaration

Habitat :: struct

Values

is_humid

An indicator of whether the habitat is humid.

Declaration

is_humid: bool

is_warm

An indicator of whether the habitat is warm.

Declaration

is_warm: bool

See Also

Declaration

Schedule :: struct

Values

events

The actions a sloth performs at scheduled times.

Declaration

events: map[int]Event

See Also

Struct

`Sloth`

A model representing a sloth.

Sloths are mammals known for their slowness of movement. They spend most of their lives hanging upside down in trees.

You can create a sloth using the init_sloth/3 initializer, or create a randomly generated sloth using Generators/generate_sloth/1:

habitat := Sloth.init_habitat(is_humid = true, is_warm = true)

sloth := Generators.generate_sloth(habitat)

Declaration

Sloth :: struct

Values

name

The name of the sloth.

Declaration

name: string

color

The color of the sloth.

Declaration

color: Color

power

The power of the sloth.

Declaration

power: Power

energy_level

The energy level of the sloth.

Sloths have a very low metabolic rate, so their energy level is often low as well. It’s important to check their energy level often, and offer them food or opportunities to sleep before asking them to perform an activity or exercise.

You can increase the sloth’s energy level by asking them to sloth_eat/3 or sloth_sleep/3.

Declaration

energy_level: int

schedule

The care schedule of the sloth.

A care schedule maintains the health and happiness of the sloth.

Declaration

schedule: Schedule

See Also

Declaration

@(rodata)
SlothFood := [SlothFoodEnum]Food

Values

.Twig

A spindly stick

Declaration

.Twig = Food{name = "Twig", energy = 1}

.Regular_Leaf

A regular-sized leaf.

Declaration

.Regular_Leaf = Food{name = "Regular Leaf", energy = 2},

.Regular_Leaf

A large leaf.

Declaration

.Large_Leaf = Food{name = "Large Leaf", energy = 5},

See Also

Declaration

init_food :: proc(name: string, energy: int) -> Food

See Also

Declaration

init_schedule :: proc(events: map[int]Event) -> Schedule

See Also

Declaration

init_habitat :: proc(is_humid: bool, is_warm: bool) -> Habitat

See Also

Declaration

habitat_comfort_level :: proc(habitat: Habitat) -> int

See Also

Declaration

init_sloth :: proc(name: string, color: Color = .Yellow, power: Power = .None) -> Sloth

See Also

Procedure

`sloth_eat/3`

Eat the provided specialty sloth food.

Sloths love to eat while they move very slowly through their rainforest habitats. They are especially happy to consume leaves and twigs, which they digest over long periods of time, mostly while they sleep.

When they eat food, a sloth’s energy_level increases by the food’s Food/energy. You can feed a sloth any custom Food that you define yourself, or you can feed them one of the standard foods of Food/Twig, Food/Large_Leaf, or Food/Regular_Leaf:

sloth_eat(sleepy_sloth, .Twig)

flower := Food{name = "Flower Bud", energy = 10}
sloth_eat(super_sloth, flower)

By default, the sloth eats one of the food items you provide, but you can also specify how many of the items the sloth should eat if you have an abundance to share with them:

twig := SlothFoodEnum[.Twig]
sloth_eat(twig_happy_slot, twig, 10)

Parameters

name: The name of the sloth.
color: The color of the sloth.
power: The power of the sloth.

Returns

The sloth’s energy level after eating.

Declaration

sloth_eat :: proc {
    sloth_eat_food,
    sloth_eat_default_food,
}

See Also

Declaration

sloth_eat_food :: proc(sloth : Sloth, food: Food, quantity: int = 1) -> int

See Also

Declaration

sloth_eat_default_food :: proc(sloth: Sloth, food : SlothFoodEnum, quantity: int = 1) -> int

See Also

Procedure

`sloth_sleep/3`

Sleep in the specified habitat for a number of hours.

Sloths need to sleep for a large number of hours each day because of their low metabolic rate. Each time the sloth sleeps, their energy_level increases every hour by the habitat’s Habitat/comfort_level.

By default, the sloth sleeps for 12 hours:

sloth_sleep(tired_sloth, lovely_habitat)

You can also specify a custom number of hours:

sloth_sleep(nearly_awake_sloth, lovely_habitat, 3)

Parameters

habitat: The location for the sloth to sleep.
number_of_hours: The number of hours for the sloth to sleep. Default 12 hours.

Returns

The sloth’s energy level after sleeping.

Declaration

sloth_sleep :: proc(sloth: Sloth, habitat: Habitat, number_of_hours: int = 12) -> int

See Also

Declaration

sloth_perform :: proc(sloth: Sloth) -> Speed

See Also

Topics

Procedures

Declaration

generate_food :: proc{
    generate_food_from_habitat,
    generate_random_food,
}

See Also

Declaration

generate_food_from_habitat :: proc(habitat: Sloth.Habitat) -> Sloth.Food

See Also

Declaration

generate_random_food :: proc() -> Sloth.Food

See Also

Declaration

generate_name :: proc(seed: int = 0) -> string

See Also

generate_name/1

Declaration

generate_sloth :: proc(habitat: Sloth.Habitat) -> (sloth: Sloth.Sloth, ok: bool) #optional_ok

See Also

generate_sloth/1