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.

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.

Document generation can be divided in several type of documents:

  • Batch documents (all automated documents)
  • Interactive documents (documents that can not be produced automatically)
  • Text block correspondence (documents created based on pre-defined text blocks)
  • Forms (forms for websites)

You can place every type of document you come across in one of these categories. A lot of software solutions are offered on the Internet that can automate these processes. In particular, some integrated development environments provide interactive access to documentation, code metadata, etc.

From http://en.wikipedia.org/wiki/Documentation_generator

52 questions
25
votes
4 answers

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 definitely agree that Gherkin, or whichever feature…
MattiSG
  • 1,932
  • 2
  • 13
  • 16
22
votes
5 answers

How-to convince company to start documenting for legacy software

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 all) documentation. Not only do the developers in…
arin
  • 430
  • 2
  • 12
21
votes
6 answers

How do I document my code for minimum time review?

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, sequence diagrams, and so on). I just want to know…
21
votes
1 answer

Duplicating documentation on interface implementations/overrides good or bad?

So we have an interface like so /// /// Interface for classes capable of creating foos /// public interface ICreatesFoo { /// /// Creates foos /// void Create(Foo foo); /// /// Does Bar…
Earlz
  • 22,658
  • 7
  • 46
  • 60
13
votes
8 answers

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 run on the sources so the output can be seen in…
Patrick
  • 561
  • 4
  • 10
12
votes
3 answers

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 change? (Yeah, I know, those methods shouldn't be…
11
votes
5 answers

What are the deliverables to give to the client for a web application ?

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 documentation and the architecture information to the…
10
votes
1 answer

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 PHP code to the files and tell it to save as .php,…
Cole Tobin
  • 1,440
  • 1
  • 15
  • 28
8
votes
5 answers

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 method signature) but also the mathematical…
SRKX
  • 1,939
  • 1
  • 15
  • 24
7
votes
1 answer

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 most complete (or so it seems), but what is…
7
votes
1 answer

Standardized code documentation format, where is it?

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 is used for Java (duh), PHP (PHPDocumentor,…
dukeofgaming
  • 13,943
  • 6
  • 50
  • 77
6
votes
2 answers

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 version (e.g.: for a REST API) the same as project…
6
votes
1 answer

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 the client to select the best representation of the…
Jason
  • 179
  • 5
6
votes
1 answer

documentation of typescript code

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 parameters, what it returns and side-effects etc. It is…
Max Beikirch
  • 1,029
  • 1
  • 8
  • 6
6
votes
5 answers

How do you keep track of the meaning of your SQL fields?

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 Management Studio (SQL Server) to design my database in…
1
2 3 4