dagger / dagger

An engine to run your pipelines in containers

Home Page:https://dagger.io

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Expand on when context needed or not in Go docs. Examples to reflect.

jpadams opened this issue · comments

What is the issue?

Today we have a note box in the docs that says

https://docs.dagger.io/manuals/developer/go/264203/functions/

NOTE
The context and error return are optional in the module's function signature; remove them if you don't need them.

but not all developers will know when they need them or not.

In fact we have a Hello function that uses context, but doesn't need it, which is confusing.

We should expand to say something like

NOTE
The context and error return are optional in the module's function signature. Remove `context` in arguments if you don't need to use it in a leaf/terminal function like Stdout(ctx), Export(ctx, ...), Publish(ctx, ...). Remove `error` in return values if you handle all errors within the module and don't need to propogate them.

We should simplify the Hello function to remove context since it doesn't need it.

func (m *MyModule) Hello(
    // +optional
    name string,
) (string, error) {
    if name != "" {
        return fmt.Sprintf("Hello, %s", name), nil
    } else {
        return "Hello, world", nil
    }
}