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.
50
questions
1
vote
1answer
38 views
AMQP messaging: How to document 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
1answer
86 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 ...
3
votes
1answer
159 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,...
-2
votes
1answer
76 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 ...
0
votes
1answer
518 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>
...
2
votes
2answers
654 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 ...
21
votes
6answers
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, ...
3
votes
2answers
566 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 ...
2
votes
1answer
132 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 ...
6
votes
2answers
184 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
1answer
125 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 ...
0
votes
2answers
854 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 ...
6
votes
1answer
1k 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 ...
2
votes
0answers
251 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 ...
2
votes
1answer
201 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 ...
