Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jgit-dev] API Communication around "Replace deprecated Tag, Commit usage with RevTag, RevCommit"

Chris Aniszczyk <caniszczyk@xxxxxxxxx> wrote:
> On commit aa1733a1b61ee86340206b02f5c090eacb8c4a0b (in EGit land)...
> 
> "Replace deprecated Tag, Commit usage with RevTag, RevCommit
> 
> JGit is changing its API to no longer make Tag and Commit classes
> accessible for reading purposes.  The only thing they will support
> is the creation of new objects, and even then their APIs are moving
> to a simpler and more consistent usage style.
> 
> Replace relevant uses of tags and commits with their RevWalk based
> variants, fixing any build breakages caused by this JGit change."
> 
> So are you saying that clients aren't suppose to reference Tags at
> all?

Aren't supposed to use Commit or Tag for *reading*.  They now exist
only for creation of new objects.  I'm also considering renaming
them TagBuilder and CommitBuilder.  :-)

> Regardless what, our documentation (javadoc included) should be
> updated properly.

I thought I did that:

  /**
   * Mutable builder to construct a commit recording the state of a project.
   *
   * Applications should use this object when they need to manually construct a
   * commit and want precise control over its fields. For a higher level interface
   * see {@link org.eclipse.jgit.api.CommitCommand}.
   */
  public class Commit {

But I see it doesn't tell you not to use this for reading.  I'll add
some docs to point readers to RevWalk instead.

> Just looking for some clarification around API
> intentions. I would probably also suggest we use PDE API Tools to
> annotate some of our classes with information like (@noreference,
> @noinstantiate etc...) to help us as we develop.

Not sure how @noreference and @noinstantiate can help here.
Just guessing but @noreference means we can't use the type at all,
but you need to use this type to make a Commit.  And @noinstantiate
is the same way.

FWIW, Java already offers ways to prevent code from using a type
incorrectly.  Its called "not making it public".  The PDE stuff
is just a bandaid layered on top of the Java platform because
people wanted to do cross-package code that shouldn't have been
cross-package in the first place.

-- 
Shawn.


Back to the top