Add comment documentation

Author: Kapil Borle

src/PowerShellEditorServices.Protocol/Server/LanguageServer.cs

@@ -1091,7 +1091,6 @@ protected async Task HandleCommentHelpRequest(
             var result = new CommentHelpRequestResult();
             if (functionDefinitionAst != null)
             {
-                // todo create a semantic marker api that take only string
                 var analysisResults = await EditorSession.AnalysisService.GetSemanticMarkersAsync(
                     functionDefinitionAst.Extent.Text,
                     AnalysisService.GetCommentHelpRuleSettings(

src/PowerShellEditorServices/Language/LanguageService.cs

@@ -539,7 +539,13 @@ public FunctionDefinitionAst GetFunctionDefinitionAtLine(
             return functionDefinitionAst as FunctionDefinitionAst;
         }
 
-        // todo add xml doc
+        /// <summary>
+        /// Finds a function definition that follows or contains the given line number.
+        /// </summary>
+        /// <param name="scriptFile">Open script file.</param>
+        /// <param name="lineNumber">The 1 based line on which to look for function definition.</param>
+        /// <param name="helpLocation"></param>
+        /// <returns>If found, returns the function definition, otherwise, returns null.</returns>
         public FunctionDefinitionAst GetFunctionDefinitionForHelpComment(
             ScriptFile scriptFile,
             int lineNumber,
@@ -553,10 +559,10 @@ public FunctionDefinitionAst GetFunctionDefinitionForHelpComment(
                 return funcDefnAst;
             }
 
+            // find all the script definitions that contain the line `lineNumber`
             var foundAsts = scriptFile.ScriptAst.FindAll(
                 ast =>
                 {
-                    // find all the script definitions that contain the line `lineNumber`
                     var fdAst = ast as FunctionDefinitionAst;
                     if (fdAst == null)
                     {
@@ -570,10 +576,10 @@ public FunctionDefinitionAst GetFunctionDefinitionForHelpComment(
 
             if (foundAsts != null && foundAsts.Any())
             {
+                // of all the function definitions found, return the innermost function
+                // definition that contains `lineNumber`
                 funcDefnAst = foundAsts.Cast<FunctionDefinitionAst>().Aggregate((x, y) =>
                 {
-                    // of all the function definitions found, return the innermost function definition that contains
-                    // `lineNumber`
                     if (x.Extent.StartOffset >= y.Extent.StartOffset && x.Extent.EndOffset <= x.Extent.EndOffset)
                     {
                         return x;
@@ -582,10 +588,7 @@ public FunctionDefinitionAst GetFunctionDefinitionForHelpComment(
                     return y;
                 });
 
-                // TODO fix help completion in nested functions
                 // TODO use tokens to check for non empty character instead of just checking for line offset
-                // check if the line number is the first line in the function body
-                // check if the line number is the last line in the function body
                 if (funcDefnAst.Body.Extent.StartLineNumber == lineNumber - 1)
                 {
                     helpLocation = "begin";