Add some missing @Nullable/@NotNull annotation and JavaDoc in tasks API classes and concrete repositories

plugins/github/src/org/jetbrains/plugins/github/tasks/GithubRepository.java

@@ -237,17 +237,18 @@ public class GithubRepository extends BaseRepositoryImpl {
   }
 
   @Nullable
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     Matcher matcher = myPattern.matcher(taskName);
     return matcher.find() ? matcher.group(1) : null;
   }
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     return createTask(GithubApiUtil.getIssue(getAuthData(), getRepoAuthor(), getRepoName(), id));
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new GithubRepository(this);

plugins/tasks/tasks-api/src/com/intellij/tasks/TaskRepository.java

@@ -55,6 +55,13 @@ public abstract class TaskRepository {
    */
   public static final int NATIVE_SEARCH = 0x0010;
 
+  /**
+   * URL of the server to be used in requests. For more human-readable name of repository (e.g. some imaginary URL containing name of
+   * selected project), that will be used in settings, use {@link #getPresentableName()}.
+   *
+   * @return URL of the server
+   * @see #getPresentableName()
+   */
   @Attribute("url")
   public String getUrl() {
     return trimTrailingSlashes(myUrl);
@@ -68,6 +75,11 @@ public abstract class TaskRepository {
     return StringUtil.isNotEmpty(getUrl());
   }
 
+  /**
+   * Shared repositories will be visible in visible in other projects, but only their URL will be initialized there.
+   *
+   * @return whether repository is shared
+   */
   @Attribute("shared")
   public boolean isShared() {
     return myShared;
@@ -158,17 +170,24 @@ public abstract class TaskRepository {
    * @throws Exception
    */
   @Nullable
-  public abstract Task findTask(String id) throws Exception;
+  public abstract Task findTask(@NotNull String id) throws Exception;
 
+  @NotNull
   public abstract TaskRepository clone();
 
   @Nullable
-  public abstract String extractId(String taskName);
+  public abstract String extractId(@NotNull String taskName);
 
   /**
+   * Update state of the task on server. Don't forget to add {@link #STATE_UPDATING} in {@link #getFeatures()} and
+   * supported states in {@link TaskRepositoryType#getPossibleTaskStates()}.
+   *
+   * @param task  issue to update
+   * @param state new state of the issue
    * @see com.intellij.tasks.TaskRepositoryType#getPossibleTaskStates()
+   * @see com.intellij.tasks.TaskRepository#getFeatures()
    */
-  public void setTaskState(Task task, TaskState state) throws Exception {
+  public void setTaskState(@NotNull Task task, @NotNull TaskState state) throws Exception {
     throw new UnsupportedOperationException("Setting task to state " + state + " is not supported");
   }
 
@@ -232,7 +251,7 @@ public abstract class TaskRepository {
     return myCommitMessageFormat;
   }
 
-  public void setCommitMessageFormat(final String commitMessageFormat) {
+  public void setCommitMessageFormat(@NotNull String commitMessageFormat) {
     myCommitMessageFormat = commitMessageFormat;
   }
 
@@ -250,7 +269,7 @@ public abstract class TaskRepository {
   }
 
   @Nullable
-  public String getTaskComment(Task task) {
+  public String getTaskComment(@NotNull Task task) {
     return isShouldFormatCommitMessage()
            ? myCommitMessageFormat.replace("{id}", task.getId()).replace("{summary}", task.getSummary())
            : null;

plugins/tasks/tasks-api/src/com/intellij/tasks/impl/BaseRepository.java

@@ -21,6 +21,7 @@ import com.intellij.tasks.TaskRepository;
 import com.intellij.tasks.TaskRepositoryType;
 import com.intellij.util.xmlb.annotations.Tag;
 import com.intellij.util.xmlb.annotations.Transient;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 import java.util.regex.Matcher;
@@ -85,6 +86,7 @@ public abstract class BaseRepository extends TaskRepository {
     }
   }
 
+  @NotNull
   @Override
   public abstract BaseRepository clone();
 
@@ -131,7 +133,7 @@ public abstract class BaseRepository extends TaskRepository {
   }
 
   @Nullable
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     Matcher matcher = PATTERN.matcher(taskName);
     return matcher.find() ? matcher.group() : null;
   }

plugins/tasks/tasks-core/jira/src/com/intellij/tasks/jira/JiraRepository.java

@@ -76,6 +76,7 @@ public class JiraRepository extends BaseRepositoryImpl {
   }
 
 
+  @NotNull
   public JiraRepository clone() {
     return new JiraRepository(this);
   }
@@ -99,7 +100,7 @@ public class JiraRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     ensureApiVersionDiscovered();
     return myApiVersion.findTask(id);
   }
@@ -253,7 +254,7 @@ public class JiraRepository extends BaseRepositoryImpl {
   }
 
   @Override
-  public void setTaskState(Task task, TaskState state) throws Exception {
+  public void setTaskState(@NotNull Task task, @NotNull TaskState state) throws Exception {
     myApiVersion.setTaskState(task, state);
   }
 

plugins/tasks/tasks-core/src/com/intellij/tasks/fogbugz/FogBugzRepository.java

@@ -219,7 +219,7 @@ public class FogBugzRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     Task[] tasks = getCases(id);
     switch (tasks.length) {
       case 0:
@@ -232,6 +232,7 @@ public class FogBugzRepository extends BaseRepositoryImpl {
     }
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new FogBugzRepository(this);

plugins/tasks/tasks-core/src/com/intellij/tasks/generic/GenericRepository.java

@@ -139,6 +139,7 @@ public class GenericRepository extends BaseRepositoryImpl {
     myResponseHandlersMap.put(ResponseType.TEXT, getTextResponseHandlerDefault());
   }
 
+  @NotNull
   @Override
   public GenericRepository clone() {
     return new GenericRepository(this);
@@ -242,7 +243,7 @@ public class GenericRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(final String id) throws Exception {
+  public Task findTask(@NotNull final String id) throws Exception {
     List<TemplateVariable> variables = concat(getAllTemplateVariables(), new TemplateVariable("id", id));
     String requestUrl = substituteTemplateVariables(getSingleTaskUrl(), variables);
     HttpMethod method = getHttpMethod(requestUrl, mySingleTaskMethodType);

plugins/tasks/tasks-core/src/com/intellij/tasks/gitlab/GitlabRepository.java

@@ -83,6 +83,7 @@ public class GitlabRepository extends NewBaseRepositoryImpl {
     return true;
   }
 
+  @NotNull
   @Override
   public GitlabRepository clone() {
     return new GitlabRepository(this);
@@ -100,7 +101,7 @@ public class GitlabRepository extends NewBaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     return new GitlabTask(this, myCurrentProject, fetchIssue(Integer.parseInt(id)));
   }
 

plugins/tasks/tasks-core/src/com/intellij/tasks/lighthouse/LighthouseRepository.java

@@ -53,6 +53,7 @@ public class LighthouseRepository extends BaseRepositoryImpl {
     super(type);
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new LighthouseRepository(this);
@@ -213,7 +214,7 @@ public class LighthouseRepository extends BaseRepositoryImpl {
   }
 
   @Nullable
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     Matcher matcher = myPattern.matcher(taskName);
     return matcher.find() ? matcher.group(1) : null;
   }
@@ -257,7 +258,7 @@ public class LighthouseRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     final String[] split = id.split("\\-");
     final String projectId = split[0];
     final String realId = split[1];

plugins/tasks/tasks-core/src/com/intellij/tasks/mantis/MantisRepository.java

@@ -74,6 +74,7 @@ public class MantisRepository extends BaseRepositoryImpl {
     myAllProjectsAvailable = other.myAllProjectsAvailable;
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new MantisRepository(this);
@@ -81,7 +82,7 @@ public class MantisRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     Matcher matcher = ID_PATTERN.matcher(taskName);
     return matcher.find() ? matcher.group() : null;
   }
@@ -138,7 +139,7 @@ public class MantisRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     IssueData data = fetchIssueById(createSoap(), id);
     // sanity check
     if (data == null || data.getId() == null || data.getSummary() == null) {

plugins/tasks/tasks-core/src/com/intellij/tasks/pivotal/PivotalTrackerRepository.java

@@ -263,7 +263,7 @@ public class PivotalTrackerRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(final String id) throws Exception {
+  public Task findTask(@NotNull final String id) throws Exception {
     final String realId = getRealId(id);
     if (realId == null) return null;
     final String url = API_URL + "/projects/" + myProjectId + "/stories/" + realId;
@@ -282,11 +282,12 @@ public class PivotalTrackerRepository extends BaseRepositoryImpl {
   }
 
   @Nullable
-  public String extractId(final String taskName) {
+  public String extractId(@NotNull final String taskName) {
     Matcher matcher = myPattern.matcher(taskName);
     return matcher.find() ? matcher.group(1) : null;
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new PivotalTrackerRepository(this);
@@ -322,7 +323,7 @@ public class PivotalTrackerRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public String getTaskComment(final Task task) {
+  public String getTaskComment(@NotNull final Task task) {
     if (isShouldFormatCommitMessage()) {
       final String id = task.getId();
       final String realId = getRealId(id);
@@ -334,7 +335,7 @@ public class PivotalTrackerRepository extends BaseRepositoryImpl {
   }
 
   @Override
-  public void setTaskState(Task task, TaskState state) throws Exception {
+  public void setTaskState(@NotNull Task task, @NotNull TaskState state) throws Exception {
     final String realId = getRealId(task.getId());
     if (realId == null) return;
     final String stateName;

plugins/tasks/tasks-core/src/com/intellij/tasks/redmine/RedmineRepository.java

@@ -88,6 +88,7 @@ public class RedmineRepository extends NewBaseRepositoryImpl {
     return true;
   }
 
+  @NotNull
   @Override
   public RedmineRepository clone() {
     return new RedmineRepository(this);
@@ -155,7 +156,7 @@ public class RedmineRepository extends NewBaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     HttpGet method = new HttpGet(getRestApiUrl("issues", id + ".json"));
     IssueWrapper wrapper = getHttpClient().execute(method, new GsonSingleObjectDeserializer<IssueWrapper>(GSON, IssueWrapper.class));
     if (wrapper == null) {
@@ -196,7 +197,7 @@ public class RedmineRepository extends NewBaseRepositoryImpl {
 
   @Nullable
   @Override
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     return taskName;
   }
 

plugins/tasks/tasks-core/src/com/intellij/tasks/trac/TracRepository.java

@@ -106,7 +106,7 @@ public class TracRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     return getTask(Integer.parseInt(id), getRpcClient(), new Transport());
   }
 
@@ -230,6 +230,7 @@ public class TracRepository extends BaseRepositoryImpl {
     };
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new TracRepository(this);

plugins/tasks/tasks-core/src/com/intellij/tasks/trello/TrelloRepository.java

@@ -100,6 +100,7 @@ public final class TrelloRepository extends BaseRepositoryImpl {
     return myIncludeAllCards == repository.myIncludeAllCards;
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new TrelloRepository(this);
@@ -118,7 +119,7 @@ public final class TrelloRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     String url = TRELLO_API_BASE_URL + "/cards/" + id + "?actions=commentCard&fields=" + encodeUrl(TrelloCard.REQUIRED_FIELDS) ;
     try {
       return new TrelloTask(makeRequestAndDeserializeJsonResponse(url, TrelloCard.class), this);
@@ -175,7 +176,7 @@ public final class TrelloRepository extends BaseRepositoryImpl {
 
   @Nullable
   @Override
-  public String extractId(String taskName) {
+  public String extractId(@NotNull String taskName) {
     return TrelloUtil.TRELLO_ID_PATTERN.matcher(taskName).matches() ? taskName : null;
   }
 

plugins/tasks/tasks-core/src/com/intellij/tasks/youtrack/YouTrackRepository.java

@@ -62,6 +62,7 @@ public class YouTrackRepository extends BaseRepositoryImpl {
     super(type);
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return new YouTrackRepository(this);
@@ -158,7 +159,7 @@ public class YouTrackRepository extends BaseRepositoryImpl {
   }
 
   @Nullable
-  public Task findTask(String id) throws Exception {
+  public Task findTask(@NotNull String id) throws Exception {
     HttpMethod method = doREST("/rest/issue/byid/" + id, false);
     InputStream stream = method.getResponseBodyAsStream();
     Element element = new SAXBuilder(false).build(stream).getRootElement();
@@ -184,7 +185,7 @@ public class YouTrackRepository extends BaseRepositoryImpl {
   }
 
   @Override
-  public void setTaskState(Task task, TaskState state) throws Exception {
+  public void setTaskState(@NotNull Task task, @NotNull TaskState state) throws Exception {
     String s = myCustomStateNames.get(state);
     if (StringUtil.isEmpty(s)) {
       s = state.name();

plugins/tasks/tasks-tests/test/com/intellij/tasks/TestRepository.java

@@ -3,6 +3,7 @@ package com.intellij.tasks;
 import com.intellij.openapi.util.Condition;
 import com.intellij.tasks.impl.BaseRepository;
 import com.intellij.util.containers.ContainerUtil;
+import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
 /**
@@ -19,6 +20,7 @@ public class TestRepository extends BaseRepository {
     myTasks = tasks;
   }
 
+  @NotNull
   @Override
   public BaseRepository clone() {
     return this;
@@ -35,7 +37,7 @@ public class TestRepository extends BaseRepository {
 
   @Nullable
   @Override
-  public Task findTask(final String id) throws Exception {
+  public Task findTask(@NotNull final String id) throws Exception {
     return ContainerUtil.find(myTasks, new Condition<Task>() {
       @Override
       public boolean value(Task task) {