From bbefa87ee46d8b1887ddf9e6e36518aeeb2e4725 Mon Sep 17 00:00:00 2001 From: Runxi Yu Date: Wed, 27 May 2026 05:59:46 +0000 Subject: furgit: This should be called doc.go too --- doc.go | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ furgit.go | 71 --------------------------------------------------------------- 2 files changed, 71 insertions(+), 71 deletions(-) create mode 100644 doc.go delete mode 100644 furgit.go diff --git a/doc.go b/doc.go new file mode 100644 index 00000000..60966584 --- /dev/null +++ b/doc.go @@ -0,0 +1,71 @@ +// Package furgit provides low-level Git operations. +// +// Furgit provides absolutely no guarantees on correctness, performance, +// API stability. In particular, before version 1.0.0, no attempt at +// API stability is made at all, and breaking changes may be introduced +// in patch-level releases. See also the warranty and liability disclaimers +// in the license. +// +// Git libraries often center on a repository type that owns objects, refs, +// worktree state, and configuration behind a single facade. Furgit inverts +// that: objects are plain values, stored objects are separate types that +// associate objects with their object IDs, object storage and ref storage +// are sets of narrow interfaces consisting only of things that are truly +// reasonable for all implementations to satisfy, and every higher-level +// operation, such as commit traversal, reachability analysis, and +// recursive peeling, is built over those interfaces. +// +// While the [codeberg.org/lindenii/furgit/repository] package is where +// most users should begin, it only exists as one convenient composition of +// those pieces for the standard on-disk repository layout. Nothing inside +// furgit should depend on it; extensions to furgit such as alterntaive +// object stores must not depend on it either. +// +// # Contract labels +// +// Many furgit APIs document concurrency, dependency ownership, value lifetime, +// and close behavior using short labels. +// These labels summarize the API contract, but they do not replace the full +// doc comment on a package, type, function, method, constant, or variable. +// +// When both a type and one of its methods specify labels, the method-level +// labels take precedence for that operation. +// +// Concurrency labels: +// +// - MT-Safe: safe for concurrent use. +// - MT-Unsafe: not safe for concurrent use without external synchronization. +// +// Dependency labels: +// +// - Deps-Owned: the receiver takes ownership of all supplied dependencies +// where ownership is a reasonable concept. +// - Deps-Borrowed: the value borrows supplied dependencies. Also Life-Parent +// in most cases, unless those dependencies are not retained past +// construction. +// - Deps-Mixed: some supplied dependencies are owned and others are borrowed. +// +// Lifetime labels: +// +// - Life-Independent: returned values remain valid independently of the +// parent or provider. +// - Life-Parent: returned values are only valid while the parent or provider +// remains valid. +// - Life-Call: returned values are only valid for the duration of the +// current call, callback, or hook invocation. +// +// Close labels: +// +// - Close-Caller: the caller must close the returned value. +// - Close-No: the caller must not close the returned value directly. +// - Close-Idem: repeated Close calls are safe. +// +// Mutation labels: +// +// - Mut-Never: returned values must not be mutated. +// +// Unless Close-Idem is specified, repeated Close calls are undefined behavior. +// +// Unless a doc comment explicitly states otherwise, these labels describe the +// API contract only. They do not imply any specific implementation strategy. +package furgit diff --git a/furgit.go b/furgit.go deleted file mode 100644 index 60966584..00000000 --- a/furgit.go +++ /dev/null @@ -1,71 +0,0 @@ -// Package furgit provides low-level Git operations. -// -// Furgit provides absolutely no guarantees on correctness, performance, -// API stability. In particular, before version 1.0.0, no attempt at -// API stability is made at all, and breaking changes may be introduced -// in patch-level releases. See also the warranty and liability disclaimers -// in the license. -// -// Git libraries often center on a repository type that owns objects, refs, -// worktree state, and configuration behind a single facade. Furgit inverts -// that: objects are plain values, stored objects are separate types that -// associate objects with their object IDs, object storage and ref storage -// are sets of narrow interfaces consisting only of things that are truly -// reasonable for all implementations to satisfy, and every higher-level -// operation, such as commit traversal, reachability analysis, and -// recursive peeling, is built over those interfaces. -// -// While the [codeberg.org/lindenii/furgit/repository] package is where -// most users should begin, it only exists as one convenient composition of -// those pieces for the standard on-disk repository layout. Nothing inside -// furgit should depend on it; extensions to furgit such as alterntaive -// object stores must not depend on it either. -// -// # Contract labels -// -// Many furgit APIs document concurrency, dependency ownership, value lifetime, -// and close behavior using short labels. -// These labels summarize the API contract, but they do not replace the full -// doc comment on a package, type, function, method, constant, or variable. -// -// When both a type and one of its methods specify labels, the method-level -// labels take precedence for that operation. -// -// Concurrency labels: -// -// - MT-Safe: safe for concurrent use. -// - MT-Unsafe: not safe for concurrent use without external synchronization. -// -// Dependency labels: -// -// - Deps-Owned: the receiver takes ownership of all supplied dependencies -// where ownership is a reasonable concept. -// - Deps-Borrowed: the value borrows supplied dependencies. Also Life-Parent -// in most cases, unless those dependencies are not retained past -// construction. -// - Deps-Mixed: some supplied dependencies are owned and others are borrowed. -// -// Lifetime labels: -// -// - Life-Independent: returned values remain valid independently of the -// parent or provider. -// - Life-Parent: returned values are only valid while the parent or provider -// remains valid. -// - Life-Call: returned values are only valid for the duration of the -// current call, callback, or hook invocation. -// -// Close labels: -// -// - Close-Caller: the caller must close the returned value. -// - Close-No: the caller must not close the returned value directly. -// - Close-Idem: repeated Close calls are safe. -// -// Mutation labels: -// -// - Mut-Never: returned values must not be mutated. -// -// Unless Close-Idem is specified, repeated Close calls are undefined behavior. -// -// Unless a doc comment explicitly states otherwise, these labels describe the -// API contract only. They do not imply any specific implementation strategy. -package furgit -- cgit v1.3.1-10-gc9f91