[Lldb-commits] [lldb] 785c6b2 - [lldb][NFC] Improve documentation for CompletionRequest

[Raphael Isemann via lldb-commits]

Author: Raphael Isemann
Date: 2020-01-27T10:48:41+01:00
New Revision: 785c6b22914fa10455ef1bf349447b874bc1f37a

URL: https://github.com/llvm/llvm-project/commit/785c6b22914fa10455ef1bf349447b874bc1f37a
DIFF: https://github.com/llvm/llvm-project/commit/785c6b22914fa10455ef1bf349447b874bc1f37a.diff

LOG: [lldb][NFC] Improve documentation for CompletionRequest

Added: 
    

Modified: 
    lldb/include/lldb/Utility/CompletionRequest.h

Removed: 
    


################################################################################
diff  --git a/lldb/include/lldb/Utility/CompletionRequest.h b/lldb/include/lldb/Utility/CompletionRequest.h
index 570f626ac54e..5418efe180bf 100644
--- a/lldb/include/lldb/Utility/CompletionRequest.h
+++ b/lldb/include/lldb/Utility/CompletionRequest.h
@@ -17,16 +17,21 @@
 
 namespace lldb_private {
 enum class CompletionMode {
-  // The current token has been completed.
+  /// The current token has been completed. The client should indicate this
+  /// to the user (usually this is done by adding a trailing space behind the
+  /// token).
+  /// Example: "command sub" -> "command subcommand " (note the trailing space).
   Normal,
-  // The current token has been partially completed. This means that we found
-  // a completion, but that the completed token is still incomplete. Examples
-  // for this are file paths, where we want to complete "/bi" to "/bin/", but
-  // the file path token is still incomplete after the completion. Clients
-  // should not indicate to the user that this is a full completion (e.g. by
-  // not inserting the usual trailing space after a successful completion).
+  /// The current token has been partially completed. This means that we found
+  /// a completion, but that the token is still incomplete. Examples
+  /// for this are file paths, where we want to complete "/bi" to "/bin/", but
+  /// the file path token is still incomplete after the completion. Clients
+  /// should not indicate to the user that this is a full completion (e.g. by
+  /// not inserting the usual trailing space after a successful completion).
+  /// Example: "file /us" -> "file /usr/" (note the missing trailing space).
   Partial,
-  // The full line has been rewritten by the completion.
+  /// The full line has been rewritten by the completion.
+  /// Example: "alias name" -> "other_command full_name".
   RewriteLine,
 };
 
@@ -35,7 +40,12 @@ class CompletionResult {
   /// A single completion and all associated data.
   class Completion {
 
+    /// The actual text that should be completed. The meaning of this text
+    /// is defined by the CompletionMode.
+    /// \see m_mode
     std::string m_completion;
+    /// The description that should be displayed to the user alongside the
+    /// completion text.
     std::string m_descripton;
     CompletionMode m_mode;
 
@@ -53,9 +63,12 @@ class CompletionResult {
   };
 
 private:
+  /// List of found completions.
   std::vector<Completion> m_results;
 
-  /// List of added completions so far. Used to filter out duplicates.
+  /// A set of the unique keys of all found completions so far. Used to filter
+  /// out duplicates.
+  /// \see CompletionResult::Completion::GetUniqueKey
   llvm::StringSet<> m_added_values;
 
 public: