Stack Exchange Network

Stack Exchange network consists of 174 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange

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.

-2
votes
1answer
69 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
0answers
136 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
357 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 ...
22
votes
6answers
6k 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
135 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
119 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 ...
7
votes
2answers
149 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
99 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
487 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 ...
5
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
157 views

Standard for order of tags in PHP DocBlocks?

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
176 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
1answer
82 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 ...
1
vote
2answers
111 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 ...
0
votes
1answer
335 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
2answers
360 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 ...
2
votes
1answer
140 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 ...
1
vote
0answers
98 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 ...
7
votes
1answer
543 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 ...
1
vote
1answer
162 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. ...
14
votes
1answer
7k 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 //...
0
votes
1answer
175 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-...
7
votes
1answer
5k 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 ...
6
votes
1answer
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 ...
3
votes
1answer
151 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 ...
3
votes
1answer
281 views

Should generated documentation go in version control history?

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 ...
5
votes
2answers
165 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 ...
11
votes
3answers
1k 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 ...
3
votes
1answer
2k 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 ...
2
votes
2answers
892 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 ...
6
votes
5answers
985 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 ...
11
votes
7answers
3k 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 ...
24
votes
4answers
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 ...
7
votes
1answer
1k views

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 ...
8
votes
5answers
1k 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 ...
22
votes
5answers
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 ...
4
votes
6answers
3k 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 ...
4
votes
3answers
278 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 ...
11
votes
5answers
8k 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 ...
3
votes
3answers
445 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 {...
4
votes
2answers
530 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 ...
2
votes
4answers
1k 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 ...
4
votes
2answers
251 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 ...
2
votes
2answers
1k 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 ...
4
votes
1answer
1k views

How can the process of creating and maintaining documentation be improved?

I know it's a very subjective question , but this is one section of Software Engineering wherein I haven't seen any improvement in terms of how we can do it in a better way. I guess every programmer ...
0
votes
2answers
1k views

Best practices for documenting ASP.NET code [closed]

Any preferences for Asp.Net programmers on how to document their code? I read XML with Sandcastle is a good way to go. What do you use?
-1
votes
2answers
4k views

PDF or ebook Java API documentation [closed]

Since I have a long train ride to and from work I was wondering if there is a version of the Java API documentation floating around that I could put on my Kindle. It would be nice on the rare occasion ...