MK API: consistent usage of revision, revision id, revision number [...]

[Angela Schreiber <an...@adobe.com>]

hi

just found in the mk API that the usage of revision isn't
completely consistent:

- 'revision number'
    -> revision id was probably more appropriate

- 'revision' when referring to a String
    -> i would suggest to use again 'revision id'

and consequently only use 'revision' when really referring
to the revision.

example: MicroKernel#getHeadRevision String
          MicroKernel#waitForCommit (fixed in rev. 1325699)

- there are cases where the API/javadoc refers to a revision
   but in fact it means some sort of revision-info that
   consists of revisionID + time stamp

example: MicroKernel#getRevisions, javadoc of #getJournal

what do you think? was this worth being addressed?

angela

Re: MK API: consistent usage of revision, revision id, revision number [...]

[Michael Dürig <md...@apache.org>]

On 13.4.12 11:18, Angela Schreiber wrote:
> hi
>
> just found in the mk API that the usage of revision isn't
> completely consistent:
>
> - 'revision number'
> -> revision id was probably more appropriate
>
> - 'revision' when referring to a String
> -> i would suggest to use again 'revision id'
>
> and consequently only use 'revision' when really referring
> to the revision.
>
> example: MicroKernel#getHeadRevision String
> MicroKernel#waitForCommit (fixed in rev. 1325699)
>
> - there are cases where the API/javadoc refers to a revision
> but in fact it means some sort of revision-info that
> consists of revisionID + time stamp
>
> example: MicroKernel#getRevisions, javadoc of #getJournal
>
> what do you think? was this worth being addressed?

Yes definitely. Since there might be other implementations of that API 
against different back ends we should be very clear here. See also OAK-11.

Michael

>
> angela
>
>
>