Merge pull request #5111 from jasonmalinowski/improve-try-method-documentation

Comment our workspace Try* methods hinting you probably want something else

src/Workspaces/Core/Portable/Workspace/Solution/Document.cs

@@ -61,7 +61,8 @@ public SourceCodeKind SourceCodeKind
 
         /// <summary>
         /// Get the current syntax tree for the document if the text is already loaded and the tree is already parsed.
-        /// Returns true if the syntax tree is already available, or false if getting the syntax tree would have incurred additional work.
+        /// In almost all cases, you should call <see cref="GetSyntaxTreeAsync"/> to fetch the tree, which will parse the tree
+        /// if it's not already parsed.
         /// </summary>
         public bool TryGetSyntaxTree(out SyntaxTree syntaxTree)
         {
@@ -88,7 +89,8 @@ public bool TryGetSyntaxTree(out SyntaxTree syntaxTree)
 
         /// <summary>
         /// Get the current syntax tree version for the document if the text is already loaded and the tree is already parsed.
-        /// Returns true if the syntax tree is already available, or false if getting the syntax tree would have incurred additional work.
+        /// In almost all cases, you should call <see cref="GetSyntaxVersionAsync"/> to fetch the version, which will load the tree
+        /// if it's not already available.
         /// </summary>
         public bool TryGetSyntaxVersion(out VersionStamp version)
         {
@@ -199,7 +201,9 @@ public Task<SyntaxTree> GetSyntaxTreeAsync(CancellationToken cancellationToken =
         }
 
         /// <summary>
-        /// Gets the root node of the current syntax tree if it is available.
+        /// Gets the root node of the current syntax tree if the syntax tree has already been parsed and the tree is still cached.
+        /// In almost all cases, you should call <see cref="GetSyntaxRootAsync"/> to fetch the root node, which will parse
+        /// the document if necessary.
         /// </summary>
         public bool TryGetSyntaxRoot(out SyntaxNode root)
         {
@@ -223,7 +227,9 @@ public async Task<SyntaxNode> GetSyntaxRootAsync(CancellationToken cancellationT
         }
 
         /// <summary>
-        /// Gets the current semantic model for this document if the model is already computed.
+        /// Gets the current semantic model for this document if the model is already computed and still cached.
+        /// In almost all cases, you should call <see cref="GetSemanticModelAsync"/>, which will compute the semantic model
+        /// if necessary.
         /// </summary>
         public bool TryGetSemanticModel(out SemanticModel semanticModel)
         {

src/Workspaces/Core/Portable/Workspace/Solution/Project.cs

@@ -372,7 +372,9 @@ private static TextDocument CreateAdditionalDocument(DocumentId documentId, Proj
         }
 
         /// <summary>
-        /// Get the <see cref="Compilation"/> for this project if it is available.
+        /// Tries to get the cached <see cref="Compilation"/> for this project if it has already been created and is still cached. In almost all
+        /// cases you should call <see cref="GetCompilationAsync"/> which will either return the cached <see cref="Compilation"/>
+        /// or create a new one otherwise.
         /// </summary>
         public bool TryGetCompilation(out Compilation compilation)
         {