Ravenbrook / mps

The Memory Pool System
http://www.ravenbrook.com/project/mps
Other
563 stars 77 forks source link

MPS Sphinx extension is a bit hard to maintain #172

Open rptb1 opened 1 year ago

rptb1 commented 1 year ago

The MPS Sphinx extension is a Python module that implements some of design.mps.doc. It's not very complicated, but it's almost entirely lacking in comments or docstrings explaining:

This makes it hard to be sure, when editing the extension, that we're not introducing defects.

A once-over of the extension, adding this information and checking it against current Sphinx documentation, should sort this out.

rptb1 commented 1 year ago

I suggest at the same time we add leader comments to all the manual sources (including manual/build.txt) explaining their roles in the MPS manual and Memory Management Reference, referencing design.mps.doc for any special stuff they contain, and especially if they are processed by the MPS Sphinx extension.

See https://github.com/Ravenbrook/mps/pull/159#issuecomment-1441857416 for where this was raised.