m.dox: document a rather nasty abuse of lack of python variable scoping.

diff --git a/plugins/m/dox.py b/plugins/m/dox.py
index 7af7db0a7480ea05802a43844f2fe79b287891fe..456d0d11dace69e73b76a4b62f4e14cd14c802f1 100644 (file)
--- a/plugins/m/dox.py
+++ b/plugins/m/dox.py
@@ -121,7 +121,10 @@ def init(tagfiles, input):
                             for value in member.findall('enumvalue'):
                                 symbol_mapping[enumeration + '::' + value.text] = (None, link + '#' + value.attrib['anchor'], css_classes)
 
-                # Sections
+                # Sections. While rather strange, these reuse the `link`
+                # variable defined by whatever came earlier --- because pages
+                # have it with implicit `.html` but e.g. files with explicit
+                # `.html`. TODO: fix more robustly
                 for section in child.findall('docanchor'):
                     symbol_mapping[section.text] = (section.attrib.get('title', ''), link + '#' + section.text, css_classes)