From e8eddb31bd4d0d4cc01c5e4a546d46889b3fcfc5 Mon Sep 17 00:00:00 2001
From: Andy C <andy@oilshell.org>
Date: Tue, 14 Jan 2025 16:56:17 -0500
Subject: [PATCH] [doctools] More type annotations

---
 devtools/types.sh    |  4 ++--
 doctools/help_gen.py | 10 ++++++----
 doctools/oils_doc.py | 15 +++++++++++----
 3 files changed, 19 insertions(+), 10 deletions(-)

diff --git a/devtools/types.sh b/devtools/types.sh
index e196c70bf..0a198d883 100755
--- a/devtools/types.sh
+++ b/devtools/types.sh
@@ -61,7 +61,7 @@ check-mycpp() {
 }
 
 check-doctools() {
-  if true; then
+  if false; then
     local -a files=(
       $(for x in doctools/*.py; do echo $x; done | grep -v '_test.py' )
       lazylex/html.py
@@ -69,7 +69,7 @@ check-doctools() {
   else
     #local -a files=( lazylex/html.py )
     #local -a files=( doctools/help_gen.py )
-    local -a files=( doctools/ul_table.py lazylex/html.py )
+    local -a files=( doctools/ul_table.py lazylex/html.py doctools/oils_doc.py doctools/help_gen.py )
   fi
 
   # 777 errors before pyann
diff --git a/doctools/help_gen.py b/doctools/help_gen.py
index 02c16b495..be8a693e3 100755
--- a/doctools/help_gen.py
+++ b/doctools/help_gen.py
@@ -32,6 +32,8 @@
 import re
 import sys
 
+from typing import AnyStr
+
 from _devbuild.gen.htm8_asdl import h8_id
 from doctools import html_lib
 from doctools.util import log
@@ -239,7 +241,7 @@ def log(self, msg, *args):
             log(ind + msg, *args)
 
     def handle_starttag(self, tag, attrs):
-        # type: (str, List[Tuple[str, str]]) -> None
+        # type: (AnyStr, List[Tuple[AnyStr, AnyStr]]) -> None
         if tag in self.heading_tags:
             self.in_heading = True
             if self.cur_group:
@@ -251,7 +253,7 @@ def handle_starttag(self, tag, attrs):
         self.indent += 1
 
     def handle_endtag(self, tag):
-        # type: (str) -> None
+        # type: (AnyStr) -> None
         if tag in self.heading_tags:
             self.in_heading = False
 
@@ -259,7 +261,7 @@ def handle_endtag(self, tag):
         self.indent -= 1
 
     def handle_entityref(self, name):
-        # type: (str) -> None
+        # type: (AnyStr) -> None
         """
         From Python docs:
         This method is called to process a named character reference of the form
@@ -273,7 +275,7 @@ def handle_entityref(self, name):
                 self.cur_group[3].append(c)
 
     def handle_data(self, data):
-        # type: (str) -> None
+        # type: (AnyStr) -> None
         self.log('data %r', data)
         if self.in_heading:
             self.cur_group[2].append(data)
diff --git a/doctools/oils_doc.py b/doctools/oils_doc.py
index ef97313fb..074cc1336 100755
--- a/doctools/oils_doc.py
+++ b/doctools/oils_doc.py
@@ -14,10 +14,6 @@
 from _devbuild.gen.htm8_asdl import h8_id
 
 import cgi
-from typing import Iterator
-from typing import Any
-from typing import List
-from typing import Optional
 try:
     from cStringIO import StringIO
 except ImportError:
@@ -26,6 +22,8 @@
 import re
 import sys
 
+from typing import Iterator, Any, List, Optional, IO
+
 from doctools.util import log
 from lazylex import html
 
@@ -180,6 +178,7 @@ def __init__(self, s, start_pos, end_pos):
         self.end_pos = end_pos
 
     def PrintHighlighted(self, out):
+        # type: (html.Output) -> None
         raise NotImplementedError()
 
 
@@ -287,6 +286,7 @@ def __init__(self, s, start_pos, end_pos, chapter, linkify_stop_col):
         self.linkify_stop_col = linkify_stop_col
 
     def PrintHighlighted(self, out):
+        # type: (html.Output) -> None
         from doctools import help_gen
 
         debug_out = []
@@ -318,6 +318,8 @@ def __init__(self, s, start_pos, end_pos, lang):
         self.lang = lang
 
     def PrintHighlighted(self, out):
+        # type: (html.Output) -> None
+
         # unescape before passing to pygments, which will escape
         code = html.ToText(self.s, self.start_pos, self.end_pos)
 
@@ -329,6 +331,7 @@ def PrintHighlighted(self, out):
 
 
 def SimpleHighlightCode(s):
+    # type: (str) -> str
     """Simple highlighting for test/shell-vs-shell.sh."""
 
     f = StringIO()
@@ -540,6 +543,7 @@ def HighlightCode(s, default_highlighter, debug_out=None):
 
 
 def ExtractCode(s, f):
+    # type: (str, IO[str]) -> None
     """Print code blocks to a plain text file.
 
     So we can at least validate the syntax.
@@ -637,6 +641,7 @@ class ShellSession(object):
     """
 
     def __init__(self, shell_exe, cache_dir):
+        # type: (str, str) -> None
         """
         Args:
           shell_exe: sh, bash, osh, or oil.  Use the one in the $PATH by default.
@@ -646,6 +651,7 @@ def __init__(self, shell_exe, cache_dir):
         self.cache_dir = cache_dir
 
     def PrintHighlighted(self, s, start_pos, end_pos, out):
+        # type: (str, int, int, html.Output) -> None
         """
         Args:
           s: an HTML string.
@@ -654,6 +660,7 @@ def PrintHighlighted(self, s, start_pos, end_pos, out):
 
 
 def main(argv):
+    # type: (List[str]) -> None
     action = argv[1]
 
     if action == 'highlight':