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
0
votes
2
answers
307
views
How to automatically manage documentation
Our project consists of a cluster of microservices (let's say 20, mainly JS & PHP) that are communicating among themselves and exchanging data (via MQ) among themselves. Also, clusters have API ...
- 19
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
2
votes
1
answer
769
views
AMQP messaging: How to generate documentation for consumers?
My application publishes various messages (e.g., telemetry, changed-events, ...) to a RabbitMQ message-broker. The users have no access to the source-code and therefore, will need a separate ...
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
4
votes
1
answer
338
views
How should I document a method's computational complexity in the code?
I am currently working on a project that has very little documentation overall. The team is working to change that. I am doing my part, by adding xml comments to the methods I make and the ones I edit,...
- 151
-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
0
votes
1
answer
1k
views
Should I add XML comments in DTO models or entity models
I have 2 models, DTOs and database models (entities) that map to the database.
I usually put XML comments above the properties to describe what are they for.
class MyEntity
{
/// <summary>
...
- 1,569
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
21
votes
6
answers
7k
views
How do I document my code for minimum time review? [closed]
I want to document my code such that there is minimum need for reading and browsing the code again months later.
I know that there are different types of documentation (in source code and outside, ...
- 361
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
2
votes
1
answer
166
views
When and why during software reengineering sometimes the document reconstructing is skipped?
While studying the book of Software Engineering by author Roger Pressman I came across this point about software reengineering , where it is written in the book that if creating documentation is time ...
- 141
6
votes
2
answers
302
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 ...
1
vote
1
answer
180
views
Software component type classification [closed]
I'm writing a framework that automatically documents applications dependencies in a distributed system, the idea is to produce something close to an UML component diagram of the whole system at ...
- 127
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