You are viewing a plain text version of this content. The canonical link for it is here.
Posted to scm-dev@maven.apache.org by Wim Deblauwe <wi...@gmail.com> on 2005/11/18 13:40:59 UTC
[patch] javadoc for ScmProvider interface
Hi,
what is the correct procedure to give a patch? I have added some javadoc to
the ScmProvider class, but some of the methods still need some javadoc to
make it clear what they should do exactly. This should make it easier for
others to implement a provider.
Anyway this is the patch. I hope that someone can add what the other methods
should do exactly so I can implement them.
regards,
Wim
Index: ScmProvider.java
===================================================================
--- ScmProvider.java (revision 332738)
+++ ScmProvider.java (working copy)
@@ -16,11 +16,6 @@
* limitations under the License.
*/
-import java.io.File;
-import java.util.Date;
-import java.util.List;
-
-import org.apache.maven.scm.CommandParameters;
import org.apache.maven.scm.ScmException;
import org.apache.maven.scm.ScmFileSet;
import org.apache.maven.scm.command.add.AddScmResult;
@@ -33,11 +28,14 @@
import org.apache.maven.scm.command.tag.TagScmResult;
import org.apache.maven.scm.command.update.UpdateScmResult;
import org.apache.maven.scm.log.ScmLogger;
-import org.apache.maven.scm.login.LoginScmResult;
import org.apache.maven.scm.repository.ScmRepository;
import org.apache.maven.scm.repository.ScmRepositoryException;
import org.apache.maven.scm.repository.UnknownRepositoryStructure;
+import java.io.File;
+import java.util.Date;
+import java.util.List;
+
/**
* @author <a href="mailto:evenisse@apache.org">Emmanuel Venisse</a>
* @version $Id$
@@ -58,10 +56,32 @@
List validateScmUrl( String scmSpecificUrl, char delimiter );
- AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
+ /**
+ * Adds the given files to the source control system
+ *
+ * @param repository the source control system
+ * @param fileSet the files to be added
+ * @return an {@link AddScmResult} that contains the files that have been
added
+ * @throws ScmException
+ */
+ AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
throws ScmException;
- ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
fileSet, Date startDate, Date endDate,
+ /**
+ * Returns the changes that have happend in the source control system in a
certain period of time.
+ * This can be adding, removing, updating, ... of files
+ *
+ * @param repository the source control system
+ * @param fileSet the files to know the changes about. Implementations can
also give the changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @param startDate the start date of the period
+ * @param endDate the end date of the period
+ * @param numDays
+ * @param branch
+ * @return
+ * @throws ScmException
+ */
+ ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
fileSet, Date startDate, Date endDate,
int numDays, String branch )
throws ScmException;
@@ -74,13 +94,42 @@
DiffScmResult diff( ScmRepository repository, ScmFileSet fileSet, String
startRevision, String endRevision )
throws ScmException;
- RemoveScmResult remove( ScmRepository repository, ScmFileSet fileSet,
String message )
+ /**
+ * Removes the given files from the source control system
+ *
+ * @param repository the source control system
+ * @param fileSet the files to be removed
+ * @param message
+ * @return
+ * @throws ScmException
+ */
+ RemoveScmResult remove( ScmRepository repository, ScmFileSet fileSet,
String message )
throws ScmException;
- StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
+ /**
+ * Returns the status of the files in the source control system. The state
of each file can be one
+ * of the {@link org.apache.maven.scm.ScmFileStatus} flags.
+ *
+ * @param repository the source control system
+ * @param fileSet the files to know the status about. Implementations can
also give the changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @return
+ * @throws ScmException
+ */
+ StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
throws ScmException;
- TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tag
)
+ /**
+ * Tag (or label in some systems) will tag the source file with a certain
tag
+ *
+ * @param repository the source control system
+ * @param fileSet the files to tag. Implementations can also give the
changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @param tag the tag to apply to the files
+ * @return
+ * @throws ScmException
+ */
+ TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tag
)
throws ScmException;
UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, String
tag )
Re: [patch] javadoc for ScmProvider interface
Posted by Wim Deblauwe <wi...@gmail.com>.
ok, I'll do that next time. Thanks, Wim
2005/11/18, Emmanuel Venisse <em...@venisse.net>:
>
> The correct procedure is to attach the patch to a jira issue.
>
> I'll apply your new one.
>
> Emmanuel
>
> Wim Deblauwe a écrit :
> > Hi,
> >
> > what is the correct procedure to give a patch? I have added some javadoc
> > to the ScmProvider class, but some of the methods still need some
> > javadoc to make it clear what they should do exactly. This should make
> > it easier for others to implement a provider.
> >
> > Anyway this is the patch. I hope that someone can add what the other
> > methods should do exactly so I can implement them.
> >
> > regards,
> >
> > Wim
> >
> > Index: ScmProvider.java
> > ===================================================================
> > --- ScmProvider.java (revision 332738)
> > +++ ScmProvider.java (working copy)
> > @@ -16,11 +16,6 @@
> > * limitations under the License.
> > */
> >
> > -import java.io.File;
> > -import java.util.Date;
> > -import java.util.List;
> > -
> > -import org.apache.maven.scm.CommandParameters;
> > import org.apache.maven.scm.ScmException;
> > import org.apache.maven.scm.ScmFileSet;
> > import org.apache.maven.scm.command.add.AddScmResult;
> > @@ -33,11 +28,14 @@
> > import org.apache.maven.scm.command.tag.TagScmResult;
> > import org.apache.maven.scm.command.update.UpdateScmResult;
> > import org.apache.maven.scm.log.ScmLogger;
> > -import org.apache.maven.scm.login.LoginScmResult;
> > import org.apache.maven.scm.repository.ScmRepository;
> > import org.apache.maven.scm.repository.ScmRepositoryException;
> > import org.apache.maven.scm.repository.UnknownRepositoryStructure;
> >
> > +import java.io.File;
> > +import java.util.Date;
> > +import java.util.List;
> > +
> > /**
> > * @author <a href="mailto:evenisse@apache.org
> > <ma...@apache.org>">Emmanuel Venisse</a>
> > * @version $Id$
> > @@ -58,10 +56,32 @@
> >
> > List validateScmUrl( String scmSpecificUrl, char delimiter );
> >
> > - AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
> > + /**
> > + * Adds the given files to the source control system
> > + *
> > + * @param repository the source control system
> > + * @param fileSet the files to be added
> > + * @return an {@link AddScmResult} that contains the files that
> > have been added
> > + * @throws ScmException
> > + */
> > + AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
> > throws ScmException;
> >
> > - ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
> > fileSet, Date startDate, Date endDate,
> > + /**
> > + * Returns the changes that have happend in the source control
> > system in a certain period of time.
> > + * This can be adding, removing, updating, ... of files
> > + *
> > + * @param repository the source control system
> > + * @param fileSet the files to know the changes about.
> > Implementations can also give the changes
> > + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> > downwards.
> > + * @param startDate the start date of the period
> > + * @param endDate the end date of the period
> > + * @param numDays
> > + * @param branch
> > + * @return
> > + * @throws ScmException
> > + */
> > + ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
> > fileSet, Date startDate, Date endDate,
> > int numDays, String branch )
> > throws ScmException;
> >
> > @@ -74,13 +94,42 @@
> > DiffScmResult diff( ScmRepository repository, ScmFileSet fileSet,
> > String startRevision, String endRevision )
> > throws ScmException;
> >
> > - RemoveScmResult remove( ScmRepository repository, ScmFileSet
> > fileSet, String message )
> > + /**
> > + * Removes the given files from the source control system
> > + *
> > + * @param repository the source control system
> > + * @param fileSet the files to be removed
> > + * @param message
> > + * @return
> > + * @throws ScmException
> > + */
> > + RemoveScmResult remove( ScmRepository repository, ScmFileSet
> > fileSet, String message )
> > throws ScmException;
> >
> > - StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
> > + /**
> > + * Returns the status of the files in the source control system.
> > The state of each file can be one
> > + * of the {@link org.apache.maven.scm.ScmFileStatus} flags.
> > + *
> > + * @param repository the source control system
> > + * @param fileSet the files to know the status about.
> > Implementations can also give the changes
> > + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> > downwards.
> > + * @return
> > + * @throws ScmException
> > + */
> > + StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
> > throws ScmException;
> >
> > - TagScmResult tag( ScmRepository repository, ScmFileSet fileSet,
> > String tag )
> > + /**
> > + * Tag (or label in some systems) will tag the source file with a
> > certain tag
> > + *
> > + * @param repository the source control system
> > + * @param fileSet the files to tag. Implementations can also give
> > the changes
> > + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> > downwards.
> > + * @param tag the tag to apply to the files
> > + * @return
> > + * @throws ScmException
> > + */
> > + TagScmResult tag( ScmRepository repository, ScmFileSet fileSet,
> > String tag )
> > throws ScmException;
> >
> > UpdateScmResult update( ScmRepository repository, ScmFileSet
> > fileSet, String tag )
> >
>
>
Re: [patch] javadoc for ScmProvider interface
Posted by Emmanuel Venisse <em...@venisse.net>.
The correct procedure is to attach the patch to a jira issue.
I'll apply your new one.
Emmanuel
Wim Deblauwe a écrit :
> Hi,
>
> what is the correct procedure to give a patch? I have added some javadoc
> to the ScmProvider class, but some of the methods still need some
> javadoc to make it clear what they should do exactly. This should make
> it easier for others to implement a provider.
>
> Anyway this is the patch. I hope that someone can add what the other
> methods should do exactly so I can implement them.
>
> regards,
>
> Wim
>
> Index: ScmProvider.java
> ===================================================================
> --- ScmProvider.java (revision 332738)
> +++ ScmProvider.java (working copy)
> @@ -16,11 +16,6 @@
> * limitations under the License.
> */
>
> -import java.io.File;
> -import java.util.Date;
> -import java.util.List;
> -
> -import org.apache.maven.scm.CommandParameters;
> import org.apache.maven.scm.ScmException;
> import org.apache.maven.scm.ScmFileSet;
> import org.apache.maven.scm.command.add.AddScmResult;
> @@ -33,11 +28,14 @@
> import org.apache.maven.scm.command.tag.TagScmResult;
> import org.apache.maven.scm.command.update.UpdateScmResult;
> import org.apache.maven.scm.log.ScmLogger;
> -import org.apache.maven.scm.login.LoginScmResult;
> import org.apache.maven.scm.repository.ScmRepository;
> import org.apache.maven.scm.repository.ScmRepositoryException;
> import org.apache.maven.scm.repository.UnknownRepositoryStructure;
>
> +import java.io.File;
> +import java.util.Date;
> +import java.util.List;
> +
> /**
> * @author <a href="mailto:evenisse@apache.org
> <ma...@apache.org>">Emmanuel Venisse</a>
> * @version $Id$
> @@ -58,10 +56,32 @@
>
> List validateScmUrl( String scmSpecificUrl, char delimiter );
>
> - AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
> + /**
> + * Adds the given files to the source control system
> + *
> + * @param repository the source control system
> + * @param fileSet the files to be added
> + * @return an {@link AddScmResult} that contains the files that
> have been added
> + * @throws ScmException
> + */
> + AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
> throws ScmException;
>
> - ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
> fileSet, Date startDate, Date endDate,
> + /**
> + * Returns the changes that have happend in the source control
> system in a certain period of time.
> + * This can be adding, removing, updating, ... of files
> + *
> + * @param repository the source control system
> + * @param fileSet the files to know the changes about.
> Implementations can also give the changes
> + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> downwards.
> + * @param startDate the start date of the period
> + * @param endDate the end date of the period
> + * @param numDays
> + * @param branch
> + * @return
> + * @throws ScmException
> + */
> + ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
> fileSet, Date startDate, Date endDate,
> int numDays, String branch )
> throws ScmException;
>
> @@ -74,13 +94,42 @@
> DiffScmResult diff( ScmRepository repository, ScmFileSet fileSet,
> String startRevision, String endRevision )
> throws ScmException;
>
> - RemoveScmResult remove( ScmRepository repository, ScmFileSet
> fileSet, String message )
> + /**
> + * Removes the given files from the source control system
> + *
> + * @param repository the source control system
> + * @param fileSet the files to be removed
> + * @param message
> + * @return
> + * @throws ScmException
> + */
> + RemoveScmResult remove( ScmRepository repository, ScmFileSet
> fileSet, String message )
> throws ScmException;
>
> - StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
> + /**
> + * Returns the status of the files in the source control system.
> The state of each file can be one
> + * of the {@link org.apache.maven.scm.ScmFileStatus} flags.
> + *
> + * @param repository the source control system
> + * @param fileSet the files to know the status about.
> Implementations can also give the changes
> + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> downwards.
> + * @return
> + * @throws ScmException
> + */
> + StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
> throws ScmException;
>
> - TagScmResult tag( ScmRepository repository, ScmFileSet fileSet,
> String tag )
> + /**
> + * Tag (or label in some systems) will tag the source file with a
> certain tag
> + *
> + * @param repository the source control system
> + * @param fileSet the files to tag. Implementations can also give
> the changes
> + * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()}
> downwards.
> + * @param tag the tag to apply to the files
> + * @return
> + * @throws ScmException
> + */
> + TagScmResult tag( ScmRepository repository, ScmFileSet fileSet,
> String tag )
> throws ScmException;
>
> UpdateScmResult update( ScmRepository repository, ScmFileSet
> fileSet, String tag )
>
Re: [patch] javadoc for ScmProvider interface
Posted by Wim Deblauwe <wi...@gmail.com>.
Forget the patch, this is a better one. Only diff needs explenation now.
regards,
Wim
Index: ScmProvider.java
===================================================================
--- ScmProvider.java (revision 332738)
+++ ScmProvider.java (working copy)
@@ -16,11 +16,6 @@
* limitations under the License.
*/
-import java.io.File;
-import java.util.Date;
-import java.util.List;
-
-import org.apache.maven.scm.CommandParameters;
import org.apache.maven.scm.ScmException;
import org.apache.maven.scm.ScmFileSet;
import org.apache.maven.scm.command.add.AddScmResult;
@@ -33,11 +28,14 @@
import org.apache.maven.scm.command.tag.TagScmResult;
import org.apache.maven.scm.command.update.UpdateScmResult;
import org.apache.maven.scm.log.ScmLogger;
-import org.apache.maven.scm.login.LoginScmResult;
import org.apache.maven.scm.repository.ScmRepository;
import org.apache.maven.scm.repository.ScmRepositoryException;
import org.apache.maven.scm.repository.UnknownRepositoryStructure;
+import java.io.File;
+import java.util.Date;
+import java.util.List;
+
/**
* @author <a href="mailto:evenisse@apache.org">Emmanuel Venisse</a>
* @version $Id$
@@ -58,34 +56,124 @@
List validateScmUrl( String scmSpecificUrl, char delimiter );
- AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
+ /**
+ * Adds the given files to the source control system
+ *
+ * @param repository the source control system
+ * @param fileSet the files to be added
+ * @return an {@link AddScmResult} that contains the files that have been
added
+ * @throws ScmException
+ */
+ AddScmResult add( ScmRepository repository, ScmFileSet fileSet )
throws ScmException;
- ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
fileSet, Date startDate, Date endDate,
+ /**
+ * Returns the changes that have happend in the source control system in a
certain period of time.
+ * This can be adding, removing, updating, ... of files
+ *
+ * @param repository the source control system
+ * @param fileSet the files to know the changes about. Implementations can
also give the changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @param startDate the start date of the period
+ * @param endDate the end date of the period
+ * @param numDays
+ * @param branch
+ * @return
+ * @throws ScmException
+ */
+ ChangeLogScmResult changeLog( ScmRepository repository, ScmFileSet
fileSet, Date startDate, Date endDate,
int numDays, String branch )
throws ScmException;
- CheckInScmResult checkIn( ScmRepository repository, ScmFileSet fileSet,
String tag, String message )
+ /**
+ * Save the changes you have done into the repository. This will create a
new version of the file or
+ * directory in the repository.
+ *
+ * @param repository the source control system
+ * @param fileSet the files to check in (sometimes called commit)
+ * @param tag
+ * @param message a string that is a comment on the changes that where done
+ * @return
+ * @throws ScmException
+ */
+ CheckInScmResult checkIn( ScmRepository repository, ScmFileSet fileSet,
String tag, String message )
throws ScmException;
- CheckOutScmResult checkOut( ScmRepository repository, ScmFileSet fileSet,
String tag )
+ /**
+ * Create a copy of the repository on your local machine
+ *
+ * @param repository the source control system
+ * @param fileSet the files are copied to the {@link
org.apache.maven.scm.ScmFileSet#getBasedir()} location
+ * @param tag get the version defined by the tag
+ * @return
+ * @throws ScmException
+ */
+ CheckOutScmResult checkOut( ScmRepository repository, ScmFileSet fileSet,
String tag )
throws ScmException;
DiffScmResult diff( ScmRepository repository, ScmFileSet fileSet, String
startRevision, String endRevision )
throws ScmException;
- RemoveScmResult remove( ScmRepository repository, ScmFileSet fileSet,
String message )
+ /**
+ * Removes the given files from the source control system
+ *
+ * @param repository the source control system
+ * @param fileSet the files to be removed
+ * @param message
+ * @return
+ * @throws ScmException
+ */
+ RemoveScmResult remove( ScmRepository repository, ScmFileSet fileSet,
String message )
throws ScmException;
- StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
+ /**
+ * Returns the status of the files in the source control system. The state
of each file can be one
+ * of the {@link org.apache.maven.scm.ScmFileStatus} flags.
+ *
+ * @param repository the source control system
+ * @param fileSet the files to know the status about. Implementations can
also give the changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @return
+ * @throws ScmException
+ */
+ StatusScmResult status( ScmRepository repository, ScmFileSet fileSet )
throws ScmException;
- TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tag
)
+ /**
+ * Tag (or label in some systems) will tag the source file with a certain
tag
+ *
+ * @param repository the source control system
+ * @param fileSet the files to tag. Implementations can also give the
changes
+ * from the {@link org.apache.maven.scm.ScmFileSet#getBasedir()} downwards.
+ * @param tag the tag to apply to the files
+ * @return
+ * @throws ScmException
+ */
+ TagScmResult tag( ScmRepository repository, ScmFileSet fileSet, String tag
)
throws ScmException;
- UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet,
String tag )
+ /**
+ * Updates the copy on the local machine with the changes in the repository
+ *
+ * @param repository the source control system
+ * @param fileSet location of your local copy
+ * @param tag use the version defined by the tag
+ * @return
+ * @throws ScmException
+ */
+ UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet,
String tag )
throws ScmException;
+ /**
+ * Updates the copy on the local machine with the changes in the repository
+ *
+ * @param repository the source control system
+ * @param fileSet location of your local copy
+ * @param tag use the version defined by the tag
+ * @param lastUpdate
+ * @return
+ * @throws ScmException
+ */
UpdateScmResult update( ScmRepository repository, ScmFileSet fileSet, String
tag, Date lastUpdate )
throws ScmException;
}
2005/11/18, Wim Deblauwe <wi...@gmail.com>:
>
> Hi,
>
> what is the correct procedure to give a patch? I have added some javadoc
> to the ScmProvider class, but some of the methods still need some javadoc to
> make it clear what they should do exactly. This should make it easier for
> others to implement a provider.
>
> Anyway this is the patch. I hope that someone can add what the other
> methods should do exactly so I can implement them.
>
> regards,
>
> Wim
>
> Index: ScmProvider.java
> ===================================================================
>
[snip]