View Issue Details

IDProjectCategoryView StatusLast Update
0005655GNUnetdocumentationpublic2019-12-15 15:18
Reporternikita Assigned Tonikita  
PrioritynormalSeverityfeatureReproducibilityhave not tried
Status closedResolutionsuspended 
Product VersionGit master 
Target Version0.12.0Fixed in Version0.12.0 
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

nikita

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'

nikita

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.

nikita

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

nikita

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.

nikita

2019-07-28 16:02

developer   ~0014751

I'm closing this. I'm working on this, outside of GNUnet, so this will become available but not in a time which I see fit for tracking it within this bugtracker. Of course I will not stand in the way of anyone wanting to do this for and within gnunet, so you could re-open if anyone picks it up.

schanzen

2019-12-15 15:18

administrator   ~0015183

0.12.0 released

Issue History

Date Modified Username Field Change
2019-03-19 16:48 nikita New Issue
2019-03-19 16:48 nikita Status new => assigned
2019-03-19 16:48 nikita Assigned To => nikita
2019-04-25 10:36 nikita Note Added: 0014345
2019-04-27 18:50 nikita Note Added: 0014356
2019-04-27 19:08 nikita Note Added: 0014357
2019-06-24 19:49 nikita Status assigned => confirmed
2019-06-24 19:49 nikita Note Added: 0014582
2019-07-28 16:02 nikita Status confirmed => resolved
2019-07-28 16:02 nikita Resolution open => suspended
2019-07-28 16:02 nikita Note Added: 0014751
2019-11-30 22:38 Christian Grothoff Product Version => Git master
2019-11-30 22:38 Christian Grothoff Fixed in Version => 0.12.0
2019-11-30 22:38 Christian Grothoff Target Version => 0.12.0
2019-12-15 15:18 schanzen Note Added: 0015183
2019-12-15 15:18 schanzen Status resolved => closed