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

[Jonathan Nieder <jrnieder@gmail.com>]

Johan Herland wrote:

> --- a/notes.h
> +++ b/notes.h
> @@ -104,6 +104,10 @@ const unsigned char *get_note(struct notes_tree *t,
>   * Copy a note from one object to another in the given notes_tree.
>   *
>   * Fails if the to_obj already has a note unless 'force' is true.
> + *
> + * IMPORTANT: The changes made by copy_note() to the given notes_tree structure
> + * are not persistent until a subsequent call to write_notes_tree() returns
> + * zero.

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 --