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