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
306
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
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 ...
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
6
votes
1
answer
2k
views
Resource representations and REST API documentation tools
I find myself unsure about what exactly it means to have different representations of a RESTful resource. The canonical example is for an API to provide an endpoint - say /v1/users/:id - and allow ...
- 179
2
votes
0
answers
305
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
2
votes
1
answer
243
views
How to write proper documentation for references in a docblock? [closed]
I am adding documentation to PHP code using the phpDocs tool:
/**
* This is a summary
*
* This is a description
*
* @use This function is called here and here
*/
function doSomething(){
}
I am ...
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
1
vote
2
answers
132
views
Is there such a thing as API documentation management?
So I started thinking, what is the best practice for publishing generated documentation (e.g. Doxygen, NaturalDocs, etc.) in terms of infrastructure?
I would be generating it through continuous ...
- 14k
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 ...
1
vote
2
answers
585
views
How to write comments to explain the "why" behind the callback function when the function and parameter names are insufficient for that?
How should I approach writing comments for callback functions? I want to explain the "why" behind the function when the function and parameter names are insufficient to explain what's going on.
I ...
- 143
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
1
vote
0
answers
105
views
Is there a unified source code documentation generator? [duplicate]
I'm currently working on a client's project that involves programming in multiple languages. It has gotten to the point where the amount of source code for each language has grown to such a large ...
- 13.1k
7
votes
1
answer
632
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
1
vote
1
answer
305
views
How to embed an article in the source code?
Sometimes, I notice typos in articles (blog posts) or books in source code that appears in the body of the article. It may be an indication that the code has been manually copied and pasted (e.g. ...
- 472
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
0
votes
1
answer
197
views
Functional document from code
I am a Sr java Developer and have recently joined a new team. Here I have been asked to create a functional document looking at the code of a legacy application. This application was written about 8-...
- 121
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
6
votes
1
answer
3k
views
documentation of typescript code [closed]
my question is rather short:
How do I document typescript code properly?
I found out that for projects becoming bigger and bigger, it is important to look at a function and immediately know ...
- 1,049
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
1
answer
866
views
Should generated documentation go in version control history? [duplicate]
I'm against compiled stuff going into version control, specially when it comes to compiled binaries, however, my principles are now in question after adding doxygen support for a project.
Should the ...
- 14k
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
12
votes
3
answers
3k
views
How to document experimental or incomplete APIs like @deprecated?
Is there a good term that is similar but different than "deprecate" to mean that a method or API is in the code base but should not be used because its implementation is not complete or will likely ...
- 223
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
2
votes
2
answers
2k
views
HTML in docblock comments?
In the PEAR standards there is no reference to HTML, if its allowed or not.
http://pear.php.net/manual/en/standards.sample.php
But I see some people use HTML tags like <kbd> and stuff..
So is ...
- 23
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
13
votes
8
answers
6k
views
Where to put code documentation?
I am currently using two systems to write code documentation (am using C++):
Documentation about methods and class members are added next to the code, using the Doxygen format. On a server Doxygen is ...
- 571
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
7
votes
1
answer
2k
views
Standardized code documentation format, where is it? [closed]
I'm currently looking into API documentation generation tools and I noticed that apparently there are no efforts going on in standardization.
Javadoc style is kind of an ubiquitous convention... it ...
- 14k
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
22
votes
5
answers
2k
views
How-to convince company to start documenting for legacy software [duplicate]
It has been less than a year since I joined my current company. Their majority of sales have come from a single product that has been alive since the last 10 years. However, there is minimal (if at ...
- 430
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,478
4
votes
3
answers
383
views
What could be some pitfalls in introducing a style guide and documentation generating software in a development team?
I'm considering using appledoc, a flavor of Doxygen for use in generating Objective-C code documentation, in order to create documentation for my company's iOS apps. The idea is that a server will ...
- 143
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
3
votes
3
answers
586
views
Code mapping in .NET (or in general)
Does there exist a software solution of some form that has the ability to map out the actions of calling a function.
So what I mean is, let's say that we have the following class.
public class Foo
{...
- 453
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
2
votes
4
answers
2k
views
Documentation utility for OpenEdge ABL
I have a large system in OpenEdge ABL that could use some documentation-love. Currently a team member is working on a utility that can find methods and functions and make some "Javadoc-esque" html ...
- 1,084
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
2
votes
2
answers
2k
views
Best way to manage minutes of meeting
What is the best way of managing minutes of meeting on daily bases ? Do we have to manage the documents in a repository like VSS or it can be maintained in a excel sheet itself.
Kindly share your ...