0

I couldn't find a good term to describe the program I'm looking for so here is a description.

The problem:

If I write some documentation for a program it eventually gets outdated when the code changes. So there are invisible connections/relations between documentation and code fragments. E.g. today I read through the changelog of visual studio code (version 1.19.2) and the editor.lineNumbers option has changed. Before there were just 3 possible values for this option now there are 4 possibilities.
But the documentation (in this case a source code comment) mentions only 3 of them (at least in German).

My idea to solve this is to annotate the documentation to reference the relevant code fragments for this particular section of documentation. E.g.

in code.ts 

...
500 //could also be a switch case
501 if (editor.lineNumbers === "on") {
502 ...
503 } else if (editor.lineNumbers === "off") {
504 ...
505 }
506
...

in doc.md 

<!-- watch code.ts 500-506 -->
editor.lineNumbers controls the line numbers...

From a previous run the program knows that there are only 2 options (on/off). After changing the code e.g. adding a 3rd option and running the program again it detects that the lines between 500-506 have changed and outputs a warning.

I'm not looking for a tool to generate documentation from source code.

The tool should run on Windows or Mac.

So my question is: Is there such a program or something similar?
If not: are there any reasons against such a program?

Improve this question
5
  • It should just report which lines have changed in what file? Any VCS (Git, SVN, …) can do that. If not: what OS should it run on, and what other features shall it have?
    – Izzy
    Commented Jan 19, 2018 at 21:34
  • It should only warn if the specific line(s) changed (specified in the documentation file) not if any line changed. With Git I would need to search through all changes (in the worst case for every file changed) that were made (in one or more commits) in order to check if the documentation is still up-to-date.
    – janisdd
    Commented Jan 19, 2018 at 21:45
  • Ah, dumb me – yeah, you've specified those line numbers. But in your example, what would happen if you inserted, say, 10 lines starting at line 300? Wouldn't it then watch the wrong lines? Sure you'd get a warning, but the lines you really wanted to watch hadn't changed. Also, with no VCS involved, how should it compare? That would at least need an "initial run" and a place to store the "markers" then.
    – Izzy
    Commented Jan 19, 2018 at 22:20
  • 1
    Hm in my example above a warning would be generated (when inserting lines before 500). And you're right that isn't quite what I want (but i doubt this can be handled automatically)... but if one inspect the warning manually then one can update the lines in doc.md to match the new lines (510-516 in this case). So it can co exist with some VCS. I'm note sure if the gained value of such a tool would be bigger than the "pain" updating the doc file lines (and maybe that's why I couldn't find one). Or maybe it's just too specific.
    – janisdd
    Commented Jan 19, 2018 at 22:33
  • "Gain vs Pain" is what I had in mind, too. If such a tool exists, and really goes by line numbers … it might be useful if you never insert anything before (thinking of a "numbered list" where the lines could be used as "IDs") – but for code, I somehow doubt it.
    – Izzy
    Commented Jan 20, 2018 at 7:53

1 Answer 1

Reset to default
1

One option is to write all such code such that an enumerated type is used, document all of the values the enumerated type, (there are a few coding standard enforcement tools that can help with that), and then generate the documentation directly from the source code.

There are a couple of tools that can generate your documentation, fully or partially, from the source code these include:

  • Doxygen - C++, C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D
  • Sphinx with Autodoc and possibly Breath which uses Doxygen as a back end.
  • You own script to extract the relevant information from the source code.

It is also possible to use various round trip software engineering tools that generate the interfaces for your code and the documentation such as Rational Rose (very pricey and a very different way of working).

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.