View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0005655||GNUnet||documentation||public||2019-03-19 16:48||2019-04-25 10:36|
|Priority||normal||Severity||feature||Reproducibility||have not tried|
|Target Version||Fixed in Version|
|Summary||0005655: self-generated programming documentation|
|Description||Inspired by the GnuTLS documentation I've taken on this series of long task, not yet fully defined in words here:|
- analyze GnuTLS documentation tooling
- rewrite perl parts in languages used in our our base (C, shell, awk)
to not create a mandatory dependency on perl -> 50% of the gnutls documentation code is perl
right now we don't (or only in a manual fashion) document our functions, variables, etc.
To keep up with it you have to manually sync documentation while coding (in my opinion you ideally FIRST write documentation with the expected behavior and outcome and then write the code, but this rarely happens).
See lots of "this section has to be rewritten for (...)" in our documentation.
Read 184.108.40.206 "Looking up records", of libgnunetgns. As an example - This is not 100% accurate but whatever, this should be just a generic example. If we could have this small section generated from the code which is described in there and generate function names, prototypes, description of the parameters, etc out of the source files which define them(!) and insert the result into texinfo files which are then @included in the appropriate chapters, we'd spare ourselves a major amount of duplicate work.
Expect this to take rather long with my other responsibilities, but the outcome will be worth it.
No target version for obvious reasons.
- not affect the dependencies required for gnunet (self-contained scripts and applications),
- be portable for all systems we currently support, with initial focus on NetBSD (ie best attempts to keep the involved tools portable) with best effort support testing on Debian after I have finished the code.
|Tags||No tags attached.|
In addition to our emails, I want to clarify this a little:
- We should get Texinfo, to include it as another @include chapter
- We also should get one mdoc file per function or logical group of functions with the right cross references if possible/necessary, but a one file mdoc is okay too.
For the record, we must adjust the code. Code found in branch '5655-function_documentation'