openapi: Add comments on top of various OpenAPI doc files.

This is part of our standard approach for trying to make it easy for
folks to find relevant documentation on a system they're trying to
understand.

zerver/openapi/curl_param_value_generators.py

@@ -1,3 +1,11 @@
+# Zulip's OpenAPI-based API documentation system is documented at
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This file contains helper functions for generating cURL examples
+# based on Zulip's OpenAPI definitions, as well as test setup and
+# fetching of appropriate parameter values to use when running the
+# cURL examples as part of the tools/test-api test suite.
+
 from functools import wraps
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple
 

zerver/openapi/javascript_examples.js

@@ -4,6 +4,13 @@
 /*
   This file makes use of functional comments in a way that makes the
   code confusing with the arrow-body-style lint rule applied.
+
+  Zulip's OpenAPI-based API documentation system is documented at
+  https://zulip.readthedocs.io/en/latest/documentation/api.html
+
+  This file contains example code fenced off by comments, and is
+  designed to be run as part of Zulip's test-api test suite to verify
+  that the documented examples are all correct, runnable code.
 */
 
 const ExamplesHandler = function () {

zerver/openapi/javascript_examples.py

@@ -1,3 +1,9 @@
+# Zulip's OpenAPI-based API documentation system is documented at
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This Python file wraps the test suite for Zulip's JavaScript API
+# examples and validates the responses against our OpenAPI definitions.
+
 import json
 import os
 import subprocess

zerver/openapi/markdown_extension.py

@@ -1,3 +1,10 @@
+# Zulip's OpenAPI-based API documentation system is documented at
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This file defines the special Markdown extension that is used to
+# render the code examples, example responses, etc. that appear in
+# Zulip's public API documentation.
+
 import inspect
 import json
 import re

zerver/openapi/openapi.py

@@ -1,5 +1,10 @@
-# Set of helper functions to manipulate the OpenAPI files that define our REST
+# Zulip's OpenAPI-based API documentation system is documented at
-# API's specification.
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This file contains helper functions to interact with the OpenAPI
+# definitions and validate that Zulip's implementation matches what is
+# described in our documentation.
+
 import os
 import re
 from typing import Any, Dict, List, Optional, Set

zerver/openapi/python_examples.py

@@ -1,3 +1,17 @@
+# Zulip's OpenAPI-based API documentation system is documented at
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This file defines the Python code examples that appears in Zulip's
+# REST API documentation, and also contains a system for running the
+# example code as part of the `tools/test-api` test suite.
+#
+# The actual documentation appears within these blocks:
+#   # {code_example|start}
+#   Code here
+#   # {code_example|end}
+#
+# Whereas the surrounding code is test setup logic.
+
 import json
 import os
 import sys

zerver/openapi/test_curl_examples.py

@@ -1,3 +1,10 @@
+# Zulip's OpenAPI-based API documentation system is documented at
+#   https://zulip.readthedocs.io/en/latest/documentation/api.html
+#
+# This file contains the top-level logic for testing the cURL examples
+# in Zulip's API documentation; the details are in
+# zerver.openapi.curl_param_value_generators.
+
 import glob
 import html
 import json