View Issue Details

IDProjectCategoryView StatusLast Update
0005655GNUnetdocumentationpublic2019-06-24 19:49
Reporterng0Assigned Tong0 
PrioritynormalSeverityfeatureReproducibilityhave not tried
Status confirmedResolutionopen 
Product Version 
Target VersionFixed in Version 
Summary0005655: self-generated programming documentation
DescriptionInspired 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 7.34.1.1 "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.

This should:
- 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.
TagsNo tags attached.

Activities

ng0

2019-04-25 10:36

developer   ~0014345

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'

ng0

2019-04-27 18:50

developer   ~0014356

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.

ng0

2019-04-27 19:08

developer   ~0014357

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).

ng0

2019-06-24 19:49

developer   ~0014582

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.

Issue History

Date Modified Username Field Change
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