Editing Software documentation (section)

==== Technical documentation embedded in source code ====

Often, [[Documentation generator|tools]] such as [[Doxygen]], [[NDoc]], [[Visual Expert]], [[Javadoc]], [[JSDoc]], [[EiffelStudio]], [[Sandcastle (software)|Sandcastle]], [[ROBODoc]], [[Plain Old Documentation|POD]], [[TwinText]], or Universal Report can be used to auto-generate the code documents&mdash;that is, they extract the comments and [[Design by Contract|software contracts]], where available, from the source code and create reference manuals in such forms as text or [[HTML]] files.

The idea of auto-generating documentation is attractive to programmers for various reasons.  For example, because it is extracted from the source code itself (for example, through [[comment (computer programming)|comment]]s), the programmer can write it while referring to the code, and use the same tools used to create the source code to make the documentation.  This makes it much easier to keep the documentation up-to-date.

A possible downside is that only programmers can edit this kind of documentation, and it depends on them to refresh the output (for example, by running a [[cron job]] to update the documents nightly). Some would characterize this as a pro rather than a con.

===== Literate programming =====
Respected computer scientist [[Donald Knuth]] has noted that documentation can be a very difficult afterthought process and has advocated [[literate programming]], written at the same time and location as the [[source code]] and extracted by automatic means. The programming languages [[Haskell (programming language)|Haskell]] and [[CoffeeScript]] have built-in support for a simple form of literate programming, but this support is not widely used.

===== Elucidative programming =====
Elucidative Programming is the result of practical applications of Literate Programming in real programming contexts. The Elucidative paradigm proposes that source code and documentation be stored separately.

Often, software developers need to be able to create and access information that is not going to be part of the source file itself. Such [[annotation]]s are usually part of several software development activities, such as code walks and porting, where third-party source code is analysed in a functional way. Annotations can therefore help the developer during any stage of software development where a formal documentation system would hinder progress.