[Cleanup] Document the CrashFileManager state machine.

components/minidump_uploader/android/java/src/org/chromium/components/minidump_uploader/CrashFileManager.java

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 package org.chromium.components.minidump_uploader;
 
 import android.support.annotation.Nullable;
 
 import org.chromium.base.Log;
 import org.chromium.base.VisibleForTesting;
@@ skipping 11 matching lines @@
 import java.util.HashSet;
 import java.util.List;
 import java.util.NoSuchElementException;
 import java.util.Scanner;
 import java.util.Set;
 import java.util.UUID;
 import java.util.concurrent.TimeUnit;
 import java.util.regex.Pattern;
 
 /**
- * Responsible for the Crash Report directory. It routinely scans the directory
- * for new Minidump files and takes appropriate actions by either uploading new
- * crash dumps or deleting old ones.
+ * The CrashFileManager is responsible for managing the "Crash Reports" directory containing
+ * minidump files and shepherding them through a state machine represented by the file names. Note
+ * that some of the steps are optional:
+ *  1. foo.dmp is a minidump file, written to the directory by Breakpad.
+ * (2) foo.dmpNNNNN is a minidump file, where NNNNN is the PID (process id) of the crashing
+ *     process. This step is optional -- that is, a minidump could fail to have its PID included in
+ *     the filename. Notably, Webview-generated minidumps do not include PIDs.

[gsennton, 2017/03/20 17:18:02]

I think PIDs are included for renderer-crashes for WebView as well (but I'm not
entirely sure).

[Ilya Sherman, 2017/03/20 18:14:54]

Done.

+ * (3) foo.dmpNNNNN.try0 is a minidump file with recent logcat output attached to it. This step is
+ *     optional -- that is, logcat output might fail to be extracted for the minidump. Notably,
+ *     Webview-generated minidumps do not include logcat output.
+ *  4. foo.dmpNNNNN.tryM for M > 0 is a minidump file that's been attempted to be uploaded to the
+ *     crash server, but for which M upload attempts have failed.
+ *  5. foo.up, foo.upNNNNN, or foo.upNNNNN.tryM are all valid possible names for a successfully
+ *     uploaded file.
+ *  6. foo.skipped, foo.skippedNNNNN, or foo.skippedNNNNN.tryM are all valid possible names for a
+ *     file whose upload was skipped. An upload may be skipped, for example, if the user has not
+ *     consented to uploading crash reports. These files are marked as skipped rather than deleted
+ *     immediately to allow the user to manually initiate an upload.
+ *  7. foo.forced, foo.forcedNNNNN, or foo.forcedNNNNN.tryM are all valid possible names for a file
+ *     that the user has manually requested to upload.
+ *  8. foo.tmp is a temporary file. Notably, the Webview crash directory uses tmp files while

[gsennton, 2017/03/20 17:18:02]

Note that the tmp-files we use in WebView are stored in a different directory
(i.e. not inside "cache/Crash Reports") so they aren't handled in the same way
as other .tmp files.

[Ilya Sherman, 2017/03/20 18:14:54]

Done.

+ *     copying over minidumps from individual Webview-using apps.
  */
 public class CrashFileManager {
     private static final String TAG = "CrashFileManager";
 
     /**
      * The name of the crash directory.
      */
     public static final String CRASH_DUMP_DIR = "Crash Reports";
 
     // This should mirror the C++ CrashUploadList::kReporterLogFilename variable.
@@ skipping 529 matching lines @@
     /**
      * Create a temporary file to store a minidump in before renaming it with a real minidump name.
      * @return a new temporary file with prefix {@param prefix} stored in the directory
      * {@param directory}.
      *
      */
     private static File createMinidumpTmpFile(File directory) throws IOException {
         return File.createTempFile("webview_minidump", TMP_SUFFIX, directory);
     }
 }