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.

See more information about language support for generation programs at Comparison of documentation generators.

832 questions
28
votes
2 answers

Documenting namespaces with Doxygen

I'm having issues with Doxygen recognizing namespaces and modules. I believe the issue surrounds whether to place the \addtogroup within the namespace or outside the namespace. Example 1, outside the namespace: /*! * \addtogroup Records * @{ …
28
votes
5 answers

Using Doxygen with C, do you comment the function prototype or the definition? Or both?

I'm using Doxygen with some embedded C source. Given a .c/.h file pair, do you put Doxygen comments on the function prototype (.h file) or the function definition (.c file), or do you duplicate them in both places? I'm having a problem in which…
jparker
  • 1,569
  • 2
  • 16
  • 16
27
votes
4 answers

Using Markdown for source code documentation

I am looking for an alternative to C#'s XML source code documentation which introduced by the very nature of XML a lot of noise that is heavy on the eye and more work to write: /// /// This is text of importance. Linking to ///
chiccodoro
  • 14,407
  • 19
  • 87
  • 130
27
votes
5 answers

Generating PHP code documentation with Sphinx?

Sphinx is a Python library to generate nice documentation from a set of ReST formatted text files. Not the tool used for full-text searching I'm also fully aware of doxygen / phpdoc tools. I'm trying to figure out if there is a way of using Sphinx…
messedup
  • 1,098
  • 1
  • 10
  • 12
27
votes
2 answers

Swagger With Static Documentation

I am looking to use Swagger to document my restful interface. The problem is that I do not want to automatically generate my documentation by annotating my code. Basically I don't want to couple my internal data model to the virtual data model…
Lee Jensen
  • 2,151
  • 2
  • 21
  • 23
26
votes
1 answer

Haddock, Cabal: How to include source code examples?

I am the author of the operational package, which includes example code. I would like this example code to be hscolored and installed together with the API documentation, which is generated by Haddock. I probably have to use a custom Cabal build…
Heinrich Apfelmus
  • 11,034
  • 1
  • 39
  • 67
26
votes
5 answers

Should I include getters & setters in class diagram?

I am required to draw a class diagram for my JSF application for a project documentation. So I have lots of classes as managed beans, with many attributes therefore many getters and setters. When I draw the class diagram should I also include the…
Selvin
  • 12,333
  • 17
  • 59
  • 80
26
votes
3 answers

Generate HTML / Help files from VS 2010 C# XML documentation

I am looking for a good tool creating HTML / Help files from my VS2010 XML documentation. I have found some commercial tools, such as .Net documentation tool VSDocman I am sure there are more, I just list these two as examples. Also there are…
Horst Walter
  • 13,663
  • 32
  • 126
  • 228
26
votes
4 answers

Is doxygen the (de facto) standard documentation syntax specification?

We all have the good habit of documenting our code, right? Nowadays, in-code documentation itself has a syntax. It's almost like a programming language onto itself. The questions are: What (How many) documentation syntax specifications…
augustin
  • 14,373
  • 13
  • 66
  • 79
26
votes
3 answers

What is the Mathworks way to generate Matlab HTML documentation?

I am working on shared Matlab code and we would like to share a generated documentation as searchable HTML documents within our local network. I know of the following methods to generate a documentation: Write a converter to C++-like files. This is…
Lukas
  • 2,330
  • 2
  • 22
  • 31
25
votes
5 answers

Auto documenting REST API in PHP

phpDocumentor seems to be the standard for documenting PHP code, though I have to wonder why it hasn't been updated in years..? However, it does not seem suitable for documenting the entry points for a REST API; IE, externally accessible entry…
Greywire
  • 1,493
  • 4
  • 13
  • 14
25
votes
2 answers

How do you write your package documentation?

I haven't quite figured out a sensible workflow for building packages and writing their documentation. I want as much of the process (and the documentation) as possible to be automatically generated. The obvious way to do this seems to be to use…
Richie Cotton
  • 118,240
  • 47
  • 247
  • 360
25
votes
1 answer

Using Sphinx-apidoc to generate documentation from C++ code

There have been a couple of threads on this topic in the past that claim Sphinx doesn't support this at all. I had my doubts but either it has been updated since or the documentation for it was quite well hidden, because here is a link on the…
24
votes
3 answers

How to document Python function parameters with Sphinx?

I'm trying to clean up my python code documentation, and decided to use sphinx-doc because it looks good. I like how I can reference other classes and methods with tags like: :class:`mymodule.MyClass` About my…
Adam Morris
  • 8,265
  • 12
  • 45
  • 68
24
votes
7 answers

How to document a makefile?

Is there a way to write "standard" comments in a Makefile to later feed them to a Doxygen-like program so as to output a nice (HTML or man for instance) documentation ? I'd like to have a clear overview of my main targets somewhere but nothing too…
J.N.
  • 8,203
  • 3
  • 29
  • 39
1 2
3
55 56