5 ms·
It seems that folding code to a natural language summary is what you really want.
by jules 16y ago
It seems that folding code to a natural language summary is what you really want.
- jmillikin 16y agoNot at all; I want to be able to print stuff like this in the generated documentation: ---------------------------------------------- 3.2 HTTPS driver The HTTPS driver is currently implemented using either GNU TLS or OpenSSL: == driver includes #include <gnutls.h> #include <openssl.h> == driver list , {"HTTPS (GNU TLS)", driver_https_gnutls} , {"HTTPS (Open SSL)", driver_https_openssl} == drivers.c static void driver_https_gnutls(DriverState *s) { ||common driver local storage|| gnutls_init(); gnutls_ctx_init(&ctx); check_extra_algos = "FOO:BAR"; some_feature_flag = 1; // etc } static void driver_https_openssl(DriverState *s) { ||common driver local storage|| openssl_init(); check_extra_algos = "BAZ"; some_feature_flag = 0; // etc } ----------------------------------------------
- jules 16y agoI meant instead of pulling out a block of code and interpolating it later. For example instead of: <set up> <do stuff> <tear down> And then describing them in the rest of the document, a better solution to me seems to be able to click on e.g. the <do stuff> part to expand it. This allows the reader to see the high level structure and drill down to the stuff he's interested in instead of spreading the code all over the place with references.
- steveklabnik 16y agoThat might be an 80% solution, but it still means that you're tying your presentation to the way that the computer needs to have things ordered. What if all of the parts need explained, but I really want to explain the <do stuff> before the <set up> and <tear down>?