scripts/wrap/: added explanatory comment to FzPathWalker2 wrapper class.

This Swig Director class is slightly unusual because it requires
that the low-level fz_path_walker* is passed as the `void*` arg of
mupdf::fz_walk_path().

scripts/wrap/classes.py

@@ -237,6 +237,8 @@ def __init__( self,
 
                     Should typically set up the MuPDF struct so that `self_()`
                     can return the original C++ wrapper class instance.
+                comment:
+                    Extra comment for the wrapper class.
                 free:
                     Optional code for freeing the virtual_fnptrs wrapper
                     class. If specified this causes creation of a destructor
@@ -1211,6 +1213,19 @@ class so we simply keep a pointer to it in a global
                         *({rename.class_("fz_path_walker")}2**) (m_internal + 1) = this;
                         '''),
                     free = f'{rename.ll_fn("fz_free")}(m_internal);\n',
+                    comment = textwrap.dedent(f'''
+                            /*
+                            We require that the `void* arg` passed to callbacks
+                            is the original `fz_path_walker*`. So, for example,
+                            class-aware wrapper mupdf::fz_walk_path() should be
+                            called like:
+
+                                mupdf.FzPath path = ...;
+                                struct Walker : mupdf.FzPathWalker2 {...};
+                                Walker walker(...);
+                                mupdf::fz_walk_path(path, walker, walker.m_internal);
+                            */
+                            ''')
                     ),
                 ),
 

scripts/wrap/cpp.py

@@ -3980,12 +3980,15 @@ def class_wrapper_virtual_fnptrs(
     self_n = extras.virtual_fnptrs.pop( 'self_n', 1)
     alloc = extras.virtual_fnptrs.pop( 'alloc')
     free = extras.virtual_fnptrs.pop( 'free', None)
+    comment = extras.virtual_fnptrs.pop( 'comment', None)
     assert not extras.virtual_fnptrs, f'Unused items in virtual_fnptrs: {extras.virtual_fnptrs}'
 
     # Class definition beginning.
     #
     out_h.write( '\n')
     out_h.write( f'/** Wrapper class for struct {struct_name} with virtual fns for each fnptr; this is for use as a SWIG Director class. */\n')
+    if comment:
+        out_h.write(comment)
     out_h.write( f'struct {classname}2 : {classname}\n')
     out_h.write(  '{\n')