Re: [PATCH 01/18] (trivial) notes.h: Minor documentation fixes to copy_notes()

Johan Herland wrote:

This reminds me: I sometimes wish there were a Documentation/technical/api-notes.txt giving a high-level overview of the API, something like this to start (warning: formatting probably broken):

-- 8< -- notes API =========

So you want to write or access persistent, per-object text? The notes API might help.

Calling sequence ----------------

The caller:

* Allocates and clears a `struct notes_tree`, then fills it based on a
  new or existing notes ref with `init_notes()`.

* Adds, removes, and retrieves notes as desired:

  . To add notes: use `write_sha1_file()` to create a blob object
    containing the information to be stored, and add it to the
    in-core notes tree with `add_note()`.

  . Retrieve notes as blob objects with `get_note()`, or as
    text with `format_note()`.

  . Change which objects a note is attached to with `copy_note()`
    and `remove_note()`.

* Can iterate over all notes with `for_each_note()`.

* Can remove notes attached to missing objects with `prune_notes()`.

* (Optionally) makes changes persist with `write_notes_tree()`.

* Frees resources associated to the notes tree with `free_notes()`.

A program like 'git log' that needs to find the notes corresponding to certain objects in multiple notes trees might instead use the display notes API. In this case, the caller:

* (Optionally) prepares a `struct display_notes_opt` with settings
  about which notes trees to use.

* Initializes the display notes machinery with `init_display_notes()`.

* Retrieves notes for each object of interest with
  `format_display_notes()`.
-- >8 --