View Issue Details

IDProjectCategoryView StatusLast Update
0005655GNUnetdocumentationpublic2019-04-25 10:36
Reporterng0Assigned Tong0 
PrioritynormalSeverityfeatureReproducibilityhave not tried
Status assignedResolutionopen 
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'

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