[tools] Fix API doc string validation

.github/workflows/standard_library_tests_and_examples.yml

@@ -96,6 +96,16 @@ jobs:
 
           # Ensure `FileCheck` from the pre-installed LLVM 15 package is visible
           echo $(brew --prefix llvm@15)/bin/ >> $GITHUB_PATH
+
+      - name: Validate documentation strings
+        run: |
+          mojo doc -warn-missing-doc-strings -o /dev/null stdlib/src/ > warnings.txt 2>&1
+          ./check-file-is-empty.py warnings.txt
+          if [ $? -ne 0 ]; then
+            echo "::error::Documentation string validation failed. Please fix the issues and try again."
+            exit 1
+          fi
+
 
       - name: Run standard library tests and examples
         run: |

stdlib/docs/style-guide.md

@@ -59,6 +59,15 @@ pip install pre-commit
 pre-commit install
 ```
 
+ #### API Doc String Validation
+
+Mojo provides a command line utility, `mojo doc`, to validate the API doc strings in your code. This ensures that your doc strings are correctly formatted and consistent with the Mojo style guidelines.
+
+```bash
+> mojo doc -warn-missing-doc-strings -o /dev/null example.mojo
+All done! ✨ 🍰 ✨
+1 file left unchanged.
+```
 and that's it!
 
 #### Whitespace

stdlib/scripts/check-file-is-empty.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+# ===----------------------------------------------------------------------=== #
+# Copyright (c) 2024, Modular Inc. All rights reserved.
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions:
+# https://llvm.org/LICENSE.txt
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ===----------------------------------------------------------------------=== #
+
+import argparse
+import os
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description=(
+            "Exits successfully if the file at the given path is empty or does"
+            " not exist. Otherwise, prints the file's contents, then exits"
+            " unsuccessfully."
+        )
+    )
+    parser.add_argument("path")
+    args = parser.parse_args()
+
+    if not os.path.exists(args.path):
+        return
+
+    with open(args.path, "r") as f:
+        content = f.read().strip()
+        if content:
+            print(
+                f"error: '{args.path}' is not empty:\n{content}",
+                file=sys.stderr,
+            )
+            exit(1)
+
+
+if __name__ == "__main__":
+    main()

stdlib/scripts/check-licenses.mojo

@@ -35,6 +35,9 @@ def main():
             # this is the current file
             continue
         file_path = Path(target_paths[i])
+        file_content = file_path.read_text()
+        if file_content.startswith("#!"):
+            file_content = "\n".join(file_content.split("\n")[1:])
         if not file_path.read_text().startswith(LICENSE):
             files_without_license.append(file_path)
 

stdlib/src/builtin/reversed.mojo

@@ -97,6 +97,11 @@ fn reversed[
     Args:
         value: The list to get the reversed iterator of.
 
+    Parameters:
+        mutability: Indicates if the list is mutable or immutable.
+        self_life: The lifetime policy for the list.
+        T: The type of elements contained in the list.
+
     Returns:
         The reversed iterator of the list.
     """

stdlib/src/collections/optional.mojo

@@ -113,8 +113,13 @@ struct Optional[T: CollectionElement](CollectionElement, Boolable):
         value (for instance with `or_else`), you'll get garbage unsafe data out.
 
         Parameters:
+<<<<<<< HEAD
+            mutability: Indicates if the optional is mutable or immutable.
+            self_life: The lifetime policy for the optional.
+=======
             mutability: Whether the Optional is mutable.
             self_life: The Optional's lifetime.
+>>>>>>> upstream/nightly
 
         Returns:
             A reference to the contained data of the option as a Reference[T].