From 9979f9260e2b5b87568b988c237f76959e98bb26 Mon Sep 17 00:00:00 2001
From: Mikhail Golubev <mikhail.golubev@jetbrains.com>
Date: Tue, 3 Mar 2015 14:27:20 +0300
Subject: [PATCH] Add javadoc for TaskRepository#extractId

---
 .../src/com/intellij/tasks/TaskRepository.java      | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/plugins/tasks/tasks-api/src/com/intellij/tasks/TaskRepository.java b/plugins/tasks/tasks-api/src/com/intellij/tasks/TaskRepository.java
index c6e270fdef4e..3688742114c0 100644
--- a/plugins/tasks/tasks-api/src/com/intellij/tasks/TaskRepository.java
+++ b/plugins/tasks/tasks-api/src/com/intellij/tasks/TaskRepository.java
@@ -223,6 +223,19 @@ public abstract class TaskRepository {
   @NotNull
   public abstract TaskRepository clone();
 
+  /**
+   * Attempts to extract server ID of the issue from the ID of local task (probably restored from project settings).
+   * It's perfectly legal to return the argument unchanged, e.g. YouTrack repository does so for ID of form <tt>IDEA-123</tt>.
+   * <p/>
+   * Basically this method works as filter that tells what repository local task belongs to. If it returns not {@code null},
+   * this repository is attached to that local task and is used then to refresh it via {@link #findTask(String)},
+   * update its state via {@link #setTaskState(Task, CustomTaskState)}, etc. Because the decision is based only on syntactic
+   * structure of ID, this approach works poorly in case of several repositories with similar issue IDs, e.g. JIRA and YouTrack,
+   * and so it's a subject of change in future.
+   *
+   * @param taskName ID of the task to check
+   * @return extracted ID of the issue or {@code null} if it doesn't look as issue ID of this tracker
+   */
   @Nullable
   public abstract String extractId(@NotNull String taskName);