Questions tagged [documentation-generation]
A documentation generator is a programming tool that generates documentation intended for programmers (API documentation) or end users (End-user Guide), or both, from a set of specially commented source code files, and in some cases, binary files.
53 questions
5
votes
12
answers
5k
views
Are comments obsolete in favor of Generative AI?
With generative AI, you can just ask it to explain the code to you. In my experience, it is reliable and accurate - which cannot always be said about manual comments. I am specifically referring to ...
- 1,563
3
votes
1
answer
1k
views
Is using the doxygen @file command counter-productive?
I'm having a dilemma regarding whether or not to use Doxygen's \@file (a.k.a. \file) command:
/**
* @file my_filename.c
*
* etc. etc.
On the one hand, it's somewhat useful for you to use @file, ...
- 2,808
0
votes
1
answer
126
views
Is there an advantage of generating/hosting documentation?
I always document my Python code with numpydoc style docstrings. For my private projects, I also generate the documentation as HTML and host them. That is super helpful because this way I can Google ...
- 635
-2
votes
1
answer
97
views
A fully working webapp without architecture or complete documentation what to do
We have a webapp (ecommerce webapp) where we are currently working on. For some functions we wrote UML diagrams and ERD diagrams. We just made a high level architecture of the website. But the ...
- 107
2
votes
2
answers
1k
views
How much information should a docstring contain
I have function that takes as arguments a number of classes of average complexity.
When writing docstring for that function, I'm running into a series of questions: Should I describe (besides what ...
- 569
3
votes
2
answers
1k
views
is XML Documentation used to document the external API only?
I am using XML Documentation comments to document a new project. All of my public API methods are documented using the three slashes required for XML documentation.
My internal methods (protected ...
- 7,139
6
votes
2
answers
301
views
Keep documentation version the same as project version
In addition to this question Should Git be used for documentation and project management? Should the code be in a separate repository? I want to ask if it is recommended to keep the documentation ...
0
votes
2
answers
2k
views
Documenting embedded C code
I am starting a startup and myself and my partners are having trouble keeping up to date on each other's code and how to implement their functions. Our code is very well commented, but each of us have ...
- 109
2
votes
0
answers
306
views
Standard for order of tags in PHP DocBlocks? [closed]
Based on the tags listed from this "standard", is there an order of the tags that people typically follow? Even if it's not something that has been entirely accepted, but something proposed? I am ...
- 211
0
votes
1
answer
121
views
Aggregate documentation comments from multiple scripts into README?
After having written some python scripts with comments for documentation inside, is it a good idea and possible to aggregate the documentation comments from multiple scripts into some standalone ...
- 5,555
0
votes
1
answer
401
views
I'm making a report generator, how should I run it?
So I've started a project to generate reports for our system. These are reports that we deliver to our end customers and they are so specialized that no existing system can generate them. This is not ...
2
votes
1
answer
176
views
Shouldn't documentation be written together with tests rather than in the code?
It is popular to write documentation in the same file as the code and extract that using software to generate documents. In order to not affect performance, the documentation is written within ...
- 464
7
votes
1
answer
633
views
Is there a de facto standard documentor for Javascript?
I'm trying to document my code using JSDOC3, that has a similar syntax to PHPDocumentator / Apigen. But is there a de-facto standard for Javascript inline documentation? I think Google Closure is the ...
- 241
21
votes
1
answer
13k
views
Duplicating documentation on interface implementations/overrides good or bad?
So we have an interface like so
/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
/// <summary>
/// Creates foos
//...
- 23.1k
10
votes
1
answer
6k
views
Does doxygen support templates for the HTML output?
I've documented my code for doxygen, but I don't want the default HTML it gives. I know I can customize it by providing custom CSS, headers, footers, etc. (like GNOME does), and how I can add common ...
- 1,533
3
votes
1
answer
192
views
Documentation Generation - FiM++
This is a question I originally asked on Stack Overflow, but as a conceptual design question as opposed to a technical issue, I believe it may be more appropriate, or possibly have alternate parallel ...
- 1,106
5
votes
2
answers
265
views
Seeking advice on system documentation
I have a rating engine (it is basically an algorithm) which when I started had no formal documentation. We have created a functional specification/decomposition which is our business level document ...
- 61
3
votes
1
answer
3k
views
How to document unlimited argument parameters?
In PHP you can have a function take an infinite number of arguments like
/**
* Do abc...
*
* @since 1.0
* @param mixed $arg1 Arg description
* @return string ...
- 33
6
votes
5
answers
1k
views
How do you keep track of the meaning of your SQL fields? [closed]
The more SQL fields I add to my tables and the more primary/foreign keys I add the more I lose the overview for specific fields for certain scenarios like Get/Add/Delete/Update data.
I use SQL ...
- 267
25
votes
4
answers
2k
views
Is BDD actually writable by non-programmers?
Behavior-Driven Development with its emblematic “Given-When-Then” scenarios syntax has lately been quite hyped for its possible uses as a boundary object for software functionality assessment.
I ...
- 1,962
8
votes
5
answers
2k
views
Where should a programmer explain the extended logic behind the code?
I have developed a few quantitative libraries in C# where it is important to understand not only the classic information that goes with the XMLDoc comments (which contains basic information with the ...
- 1,939
4
votes
6
answers
5k
views
Diagram that could explain a state machine's code?
We have a lot of concepts in making diagrams like UML and flowcharting or just making up whatever boxes-and-arrows combination works at the time, but I'm looking at doing a visual diagram on something ...
- 3,488
11
votes
5
answers
12k
views
What are the deliverables to give to the client for a web application ? [closed]
I have completed a web application which is basically developed in PHP and is just another regular web application. Usually when I deliver the final production release I just handover the code ...
- 319
5
votes
2
answers
626
views
Using automated bdd-gui-tests to keep user-documentation-screenshots up do date?
Are there developpers out there, who (ab)use the CaptureScreenshot() function
of their automated gui-tests to also create uptodate-screenshots for the userdocumentation?
Background: Whithin the ...
- 7,621
4
votes
2
answers
275
views
How do I follow DRY when documenting module structure and interfaces?
In this paper, it is recommended that one document the following:
module structure
module interfaces
If I'm writing detailed module structures and interfaces in a standalone document, aren't I ...
- 1,133