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

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