search

BZFlag-Dev / bzflag.org

The bzflag.org static website
https://www.bzflag.org
MIT License
9 stars 7 forks source link

Document BZDB settings #42

Closed allejo closed 1 year ago

allejo commented 3 years ago

This is an effort to document all of the support BZDB variables used by BZFS. Feedback, corrections, and improvements are welcome!

I'm leaving this PR as a draft until I can finish documenting all of the remaining variables and creating a respective page for it on the website.

jwmelto commented 2 years ago

Not being at all connected with the documentation methodology, this feels like an inevitably intractable maintenance burden. Just the two files in the most recent commits are 80% redundant with each other. Making the same change in 2 places is a losing proposition.

Seems to me that the only viable documentation solution is tied to the code. You can either write your documentation and generate code from that (a la protobuf), or you can write your code and generate documentation from it (Doxygen). Hand-maintaining separate and unwieldy documentation metadata is begging for the docs and the code to get out of sync.

allejo commented 2 years ago

I agree 100% that documentation for these settings should live in the main BZFlag codebase; possibly inside of global.cxx? I've been thinking about bringing up that discussion on how to document this stuff in the codebase but I'm not sure about standards for the C++ world (I only know Doxygen exists).

At the very least, I think this documentation can be used as the base for migrating it to our code and then generating future versions of this file for the site from the codebase.