Make generated file use valid C++ identifiers (#31)

* Make generated file use valid C++ identifiers

* according to https://en.cppreference.com/w/cpp/language/identifiers
    * identifiers with a double underscore anywhere;
    * identifiers that begin with an underscore followed by an uppercase letter;
    * in the global namespace, identifiers that begin with an underscore.
* clang w/ `-Weverything` is including `-Wreserved-id-macro`, which
  fails with the current macro naming scheme.

* cleaned up tests a bit

* check `comments` early

* Pin clang==14.0.6

* Apply suggestion from @henryiii

---------

Co-authored-by: Henry Schreiner <HenrySchreinerIII@gmail.com>

Author: mgeplf

pybind11_mkdoc/mkdoc_lib.py

@@ -82,7 +82,7 @@ def sanitize_name(name):
     name = re.sub('<.*>', '', name)
     name = ''.join([ch if ch.isalnum() else '_' for ch in name])
     name = re.sub('_$', '', re.sub('_+', '_', name))
-    return '__doc_' + name
+    return 'mkd_doc_' + name
 
 
 def process_comment(comment):
@@ -392,19 +392,18 @@ def write_header(comments, out_file=sys.stdout):
   Do not edit! They were automatically extracted by pybind11_mkdoc.
  */
 
-#define __EXPAND(x)                                      x
-#define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...)  COUNT
-#define __VA_SIZE(...)                                   __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0))
-#define __CAT1(a, b)                                     a ## b
-#define __CAT2(a, b)                                     __CAT1(a, b)
-#define __DOC1(n1)                                       __doc_##n1
-#define __DOC2(n1, n2)                                   __doc_##n1##_##n2
-#define __DOC3(n1, n2, n3)                               __doc_##n1##_##n2##_##n3
-#define __DOC4(n1, n2, n3, n4)                           __doc_##n1##_##n2##_##n3##_##n4
-#define __DOC5(n1, n2, n3, n4, n5)                       __doc_##n1##_##n2##_##n3##_##n4##_##n5
-#define __DOC6(n1, n2, n3, n4, n5, n6)                   __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6
-#define __DOC7(n1, n2, n3, n4, n5, n6, n7)               __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
-#define DOC(...)                                         __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
+#define MKD_EXPAND(x)                                      x
+#define MKD_COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...)  COUNT
+#define MKD_VA_SIZE(...)                                   MKD_EXPAND(MKD_COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0))
+#define MKD_CAT1(a, b)                                     a ## b
+#define MKD_CAT2(a, b)                                     MKD_CAT1(a, b)
+#define MKD_DOC1(n1)                                       mkd_doc_##n1
+#define MKD_DOC2(n1, n2)                                   mkd_doc_##n1##_##n2
+#define MKD_DOC3(n1, n2, n3)                               mkd_doc_##n1##_##n2##_##n3
+#define MKD_DOC4(n1, n2, n3, n4)                           mkd_doc_##n1##_##n2##_##n3##_##n4
+#define MKD_DOC5(n1, n2, n3, n4, n5)                       mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5
+#define MKD_DOC7(n1, n2, n3, n4, n5, n6, n7)               mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
+#define DOC(...)                                           MKD_EXPAND(MKD_EXPAND(MKD_CAT2(MKD_DOC, MKD_VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
 
 #if defined(__GNUG__)
 #pragma GCC diagnostic push

tests/sample_header_test.py

@@ -1,55 +1,55 @@
-import collections
 import os
-import time
-import sysconfig
 import sys
 
-import pytest
-
 import pybind11_mkdoc
 
 DIR = os.path.abspath(os.path.dirname(__file__))
 
 
-def test_generate_headers(capsys):
-    comments = pybind11_mkdoc.mkdoc_lib.extract_all([os.path.join(DIR, "sample_header_docs", "sample_header.h")])
-    pybind11_mkdoc.mkdoc_lib.write_header(comments, sys.stdout)
+def test_generate_headers(capsys, tmp_path):
+    comments = pybind11_mkdoc.mkdoc_lib.extract_all(
+        [os.path.join(DIR, "sample_header_docs", "sample_header.h")]
+    )
+    assert ['mkd_doc_RootLevelSymbol', 'mkd_doc_drake_MidLevelSymbol'] == [c[0] for c in comments]
+
+    output = tmp_path / "docs.h"
+    with output.open("w") as fd:
+        pybind11_mkdoc.mkdoc_lib.write_header(comments, fd)
 
     res = capsys.readouterr()
 
     assert "warning" not in res.err
     assert "error" not in res.err
-    assert res.out == """\
+    assert output.read_text() == """\
 /*
   This file contains docstrings for use in the Python bindings.
   Do not edit! They were automatically extracted by pybind11_mkdoc.
  */
 
-#define __EXPAND(x)                                      x
-#define __COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...)  COUNT
-#define __VA_SIZE(...)                                   __EXPAND(__COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0))
-#define __CAT1(a, b)                                     a ## b
-#define __CAT2(a, b)                                     __CAT1(a, b)
-#define __DOC1(n1)                                       __doc_##n1
-#define __DOC2(n1, n2)                                   __doc_##n1##_##n2
-#define __DOC3(n1, n2, n3)                               __doc_##n1##_##n2##_##n3
-#define __DOC4(n1, n2, n3, n4)                           __doc_##n1##_##n2##_##n3##_##n4
-#define __DOC5(n1, n2, n3, n4, n5)                       __doc_##n1##_##n2##_##n3##_##n4##_##n5
-#define __DOC6(n1, n2, n3, n4, n5, n6)                   __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6
-#define __DOC7(n1, n2, n3, n4, n5, n6, n7)               __doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
-#define DOC(...)                                         __EXPAND(__EXPAND(__CAT2(__DOC, __VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
+#define MKD_EXPAND(x)                                      x
+#define MKD_COUNT(_1, _2, _3, _4, _5, _6, _7, COUNT, ...)  COUNT
+#define MKD_VA_SIZE(...)                                   MKD_EXPAND(MKD_COUNT(__VA_ARGS__, 7, 6, 5, 4, 3, 2, 1, 0))
+#define MKD_CAT1(a, b)                                     a ## b
+#define MKD_CAT2(a, b)                                     MKD_CAT1(a, b)
+#define MKD_DOC1(n1)                                       mkd_doc_##n1
+#define MKD_DOC2(n1, n2)                                   mkd_doc_##n1##_##n2
+#define MKD_DOC3(n1, n2, n3)                               mkd_doc_##n1##_##n2##_##n3
+#define MKD_DOC4(n1, n2, n3, n4)                           mkd_doc_##n1##_##n2##_##n3##_##n4
+#define MKD_DOC5(n1, n2, n3, n4, n5)                       mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5
+#define MKD_DOC7(n1, n2, n3, n4, n5, n6, n7)               mkd_doc_##n1##_##n2##_##n3##_##n4##_##n5##_##n6##_##n7
+#define DOC(...)                                           MKD_EXPAND(MKD_EXPAND(MKD_CAT2(MKD_DOC, MKD_VA_SIZE(__VA_ARGS__)))(__VA_ARGS__))
 
 #if defined(__GNUG__)
 #pragma GCC diagnostic push
 #pragma GCC diagnostic ignored "-Wunused-variable"
 #endif
 
 
-static const char *__doc_RootLevelSymbol =
+static const char *mkd_doc_RootLevelSymbol =
 R"doc(Root-level symbol. Magna fermentum iaculis eu non diam phasellus
 vestibulum.)doc";
 
-static const char *__doc_drake_MidLevelSymbol =
+static const char *mkd_doc_drake_MidLevelSymbol =
 R"doc(1. Begin first ordered list element. Rutrum quisque non tellus orci ac
 auctor. End first ordered list element. 2. Begin second ordered list
 element. Ipsum faucibus vitae aliquet nec. Ligula ullamcorper
@@ -66,4 +66,3 @@ def test_generate_headers(capsys):
 #endif
 
 """
-