versioned file api audit

[Martin Pool]

On 17/03/2008, Robert Collins <robertc at robertcollins.net> wrote:
> so I just audited the public interface of versioned file. Heres what I
>  propose we keep/discuss/remove from it.
>
>
>  vf apis to keep:
>  check_not_reserved_id
>  versions
>  add_lines
>   (with ghosts version/perhaps flag)
>  add_mpdiff
>   (nb, add_lines adds one version, add_mpdiffs adds many, we should make
>  these
>    consistent)
>  check (but rename validate?)
>  get_format_signature
>  make_mpdiffs (but rename to get_something, or iter_mpdiffs) ?
>  get_sha1s
>  get_parent_dict (because this is what bzrlib.graph wants; iter_parents
>  is
>     better on incremental work)

I don't see any existing function called get_parent_dict.

>  annotate_iter (perhaps rename to iter_annotations)

agree with the renaming

>  iter_lines_added_or_present_in_versions
>  weave_merge
>
>  apis to discuss:
>  plan_merge (perhaps keep this)

This is closely related to weave_merge, and so probably should be
kept.  Maybe it should be a private method and called by rather than
passed to weave_merge.

You could say perhaps this will not vary with VF implementation, and
the vf should instead just give annotation data to something else.

>
>  apis to remove:
>  has_version

Why get rid of this?

>  copy_to
>  access_mode in constructor
>  finished

agree with all of these

>  iter_parents

is this not needed?

>  join
>  annotate
>  get_sha1
>  has_ghost
>  add_lines_non_ghost
>  enable_cache
>  clear_cache

agree with all these

>  clone_text

"add a new text the same as an old one" is sometime useful; arguably
not often enough to be a special case; anyhow probably better as an
option to an add_method

>  create_empty
>  get_suffixes
>  get_text
>  get_texts
>  get_lines

are you really going to have no method to get texts back out?

>  get_ancestry
>  get_ancestry_with_ghosts

agree

>  get_graph
>  get_graph_with_ghosts

why get rid of them?  if we plan to have a per-vf graph, this seems
like the way to expose it.

>  transaction_finished

agree.

That would be a nice cleanup!
-- 
Martin <http://launchpad.net/~mbp/>