View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0005655||GNUnet||documentation||public||2019-03-19 16:48||2019-06-24 19:49|
|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'
As written on IRC, but duplicating it here in summary: I'm also evaluating a modification of
the sqlite2mdoc application, which might be less work if we can adjust it to our own infrastructure.
If not for all (LMHD, Taler, GNUnet), then for gnunet and everyone else can make patches on top of it or have their own branches.
We don't need no extra output with mdoc having the ability to output to html, texinfo, etc.
Also if we haven't put it down for public record: we don't want the output to be part of the repository but to be part of the distribution tarball.
For full reference: https://github.com/kristapsdz/sqlite2mdoc/blob/master/main.c
I'm in favor of and will use whatever leads to self-documenting code, even if we have to adjust the code to our new clang-format somehow (by code I mean comments about the code).
||working on this, in case I haven't mentioned it, with varying time I can spend on this. Do it once and do it good.|
|2019-03-19 16:48||ng0||New Issue|
|2019-03-19 16:48||ng0||Status||new => assigned|
|2019-03-19 16:48||ng0||Assigned To||=> ng0|
|2019-04-25 10:36||ng0||Note Added: 0014345|
|2019-04-27 18:50||ng0||Note Added: 0014356|
|2019-04-27 19:08||ng0||Note Added: 0014357|
|2019-06-24 19:49||ng0||Status||assigned => confirmed|
|2019-06-24 19:49||ng0||Note Added: 0014582|