====== [hemmerling] Software Documentation ======
Related pages:
  *[[goodcoding.html|Good Coding ! - Software Coding, Coding Rules, Static Code Analysis, Code Reviews]].
  *[[requirements.html|Requirements]].
  *[[systemdesign.html|System Design]]
  *[[technicalwriting.html|Technical Writing]]
  *[[testing.html|Testing]].
===== Graphical Description Notations for Description of Systems =====
<WRAP tip>See [[systemdesign.html|System Design]].</WRAP>
  *[[http://de.wikipedia.org/wiki/Taktisches_Zeichen|DE.Wikipedia: "Taktische Zeichen"]].
  *[[http://de.wikipedia.org/wiki/Milit%C3%A4rische_Lastenklasse|DE.Wikipedia: "Militärische Lastenklasse"]].
===== Software Documentation =====
==== Generators for creating Software Documentation ====
=== AsciiDoc ===
  *[[http://www.asciidoc.org/|AsciiDoc - Text based document generation]], [[http://www.methods.co.nz/asciidoc/|AsciiDoc - Text based document generation]], [[http://www.github.com/asciidoc/|GitHub "asciidoc"]] - "Text based document generation. AsciiDoc is a text document format for writing notes, documentation, articles, books, ebooks, slideshows, web pages, man pages and blogs. AsciiDoc files can be translated to many formats including HTML, PDF, EPUB, man page".
  *The OpenSource software tool [[http://www.asciidoctor.org/|Asciidoctor]],  - "A fast text processor & publishing toolchain for converting AsciiDoc to HTML5, DocBook & more".
    *[[http://www.asciidoctor.org/docs/what-is-asciidoc/|Asciidoctor "What is AsciiDoc? Why do we need it?"]].
    *[[http://www.asciidoctor.org/docs/asciidoc-writers-guide/|Asciidoctor "AsciiDoc Writer’s Guide"]].
    *[[http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/|Asciidoctor "AsciiDoc Writer’s Guide"]].
    *Plugins:
      *[[http://www.plantuml.com/|PlantUML]], [[http://en.wikipedia.org/wiki/PlantUML|EN.Wikipedia "PlantUML"]].
      *[[http://www.mathjax.org/|MathJAX]], [[http://en.wikipedia.org/wiki/MathJax|EN.Wikipedia "MathJax"]], [[http://de.wikipedia.org/wiki/MathJax|DE.Wikipedia "MathJax"]].
  *[[http://www.powerman.name/doc/asciidoc|Alex Efros, POWERMAN "AsciiDoc cheatsheet"]].
  *AciiDoctor is integrated in:
    *Gradle:
      *[[http://plugins.gradle.org/plugin/org.asciidoctor.gradle.asciidoctor|Gradle - Plugin "org.asciidoctor.gradle.asciidoctor"]].
      *[[http://www.github.com/asciidoctor/asciidoctor-gradle-plugin|GitHub "asciidoctor/asciidoctor-gradle-plugin"]].
      *[[http://danhyun.github.io/asciidoctor-gradle-examples/|GitHub.io, Rob Winch and Dan Hyun "Asciidoctor Gradle Examples"]].
    *Maven:
      *[[http://www.github.com/asciidoctor/asciidoctor-maven-plugin|GitHub "asciidoctor/asciidoctor-maven-plugin"]].
      *[[http://www.asciidoctor.org/docs/asciidoctor-maven-plugin/|Asciidoctor "Installing and Using the Asciidoctor Maven Plugin"]].
      *[[http://mvnrepository.com/artifact/org.asciidoctor|MVN Repository "Group: org.asciidoctor"]].
  *Experts told me, that AsciiDoc is primarily intended to document Java and Javascript projects.
  *[[http://en.wikipedia.org/wiki/AsciiDoc|EN.Wikipedia "AsciiDoc"]], [[http://de.wikipedia.org/wiki/AsciiDoc|DE.Wikipedia "AsciiDoc"]].
=== "Atom" Editor Package "docblockr" ===
  *[[http://www.atom.io/packages/docblockr|Atom "Docblockr Package"]] - Code documentation for "ActionScript, C, C++,, Cuda-C++, CoffeeScript, Groovy, Haxe, Java, JavaScript, ObjC, ObjC++, Php, Rust, TypeScript".
=== CppDoc ===
  *[[http://www.cppdoc.com/|CppDoc]] - "CppDoc generates HTML documentation for C++ classes".
=== DOC++ ===
  *DOC++ ( [[http://docpp.sourceforge.net/|Sourceforge "DOC++"]], [[http://www.sourceforge.net/projects/docpp|Sourceforge "DOC++"]] ) - a documentation system for C, C++, IDL and Java generating both TeX output for high quality hardcopies and HTML output for sophisticated online browsing of your documentation.
=== Doxygen ===
== The Tool ==
  *Doxygen ( [[http://www.stack.nl/~dimitri/doxygen/|Doxygen]], [[http://doxygen.sourceforge.net/|Sourceforge "Doxygen"]], [[http://www.sourceforge.net/projects/doxygen|Sourceforge "Doxygen"]] ) - free Open Source documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#.
    *[[ftp://ftp.stack.nl/pub/users/dimitri/|FTP Download "Doxygen"]].
    *Doxygen 1.6.3 ist the latest edition for Win98SE.
    *"Doxygen has built-in support to generate inheritance diagrams for C++ classes. Doxygen can use the "dot" tool from [[http://www.graphviz.org/|graphviz]] to generate more advanced diagrams and graphs".
    *[[http://en.wikipedia.org/wiki/Doxygen|EN.Wikipedia "Doxygen"]], [[http://de.wikipedia.org/wiki/Doxygen|DE.Wikipedia "Doxygen"]].
== Input Filters for Python ==
  *[[http://code.foosel.org/doxypy|code.(foosel), Ina Häußge and Philippe Neumann - "doxypy"]], [[http://www.github.com/0xCAFEBABE/doxypy|GitHub "0xCAFEBABE/doxypy"]] - "An input filter for Doxygen".
    *Doxygen settings:
      *"FILTER_SOURCE_FILES = YES".
      *Expert / Input / INPUT_FILTER = 'python /usr/local/bin/doxypy.py'".
  *[[http://www.github.com/Feneric/doxypypy|GitHub "Feneric/doxypypy"]] - A fork and successor of "doxypy".
    *Doxygen settings:
      *"Expert / Input / FILTER_PATTERNS = *.py=py_filter".
    *Batch file in "C:\Python27\Scripts\py_filter.bat":
      *"python -m doxypypy.doxypypy -a -c %1".
== Input Filters for Javascript ==
  *[[http://www.stack.nl/~dimitri/doxygen/helpers.html|Doxygen "Helper tools and scripts"]].
    *[[http://joehni.github.io/JsUnit/internal.html|GitHub.io "JsUnit" - "Internal Developer's Guide"]] - "My script will call the Perl script js2doxy.pl to generate pseudo C++. Then it calls Doxygen to generate the first version of the HTML documentation. At last text processing is done with sed to generate the JsUnit color style in the headers" :-(.
    *[[http://web.archive.org/web/*/http://xiewenjie.com/doxygen-js/use-doxygen-to-document-javascript|Archive.org "XieWenjie's blog. Around emacs, linux, etc.: 'use doxygen to document javascript'"]] ( -2013-03-13 ).
  *Dimitar Trendafilov of "Coherent Labs".
    *[[http://gist.github.com/dimitarcl/3767879|GitHub Gist "dimitarcl/Doxyfile"]] - "Documenting JavaScript with Doxygen".
    *[[http://www.coherent-labs.com/blog/documenting-javascript-with-doxygen/|Coherent Labs "Documenting JavaScript with Doxygen"]].
=== javadoc - The Java API Documentation Generator ===
  *[[http://en.wikipedia.org/wiki/Javadoc|EN.Wikipedia: "Javadoc"]], [[http://de.wikipedia.org/wiki/Javadoc|DE.Wikipedia: "Javadoc"]]
  *[[http://download.oracle.com/javase/6/docs/technotes/tools/windows/javadoc.html|Oracle: "javadoc - The Java API Documentation Generator"]].
  *The commercial "[[http://www.borland.com/us/products/together|Borland Together]]" 4.x, 5.x, 6.x editions were shipped with a Javadocs generator for Java, C++ and C#.
=== Javascript-Only Documentation Tools ===
== "ext-doc" ==
  *[[http://code.google.com/p/ext-doc/|Google Code "ext-doc. ExtJS-style JavaScript comments processor"]].
== "JSDoc" & "jsdoc-toolkit" ==
  *Current:
    *[[http://www.usejsdoc.org/|@use JSDoc]].
    *The current [[http://github.com/jsdoc3/jsdoc|Github "jsdoc3 / jsdoc"]] for Node.js -> JSDoc V.3.
    *Missing block tags, in comparison to "Doxygen": 
      *Doxygen "@date".
      *Doxygen "@brief" -> JsDoc "@summary".
  *Legacy:
    *The legacy [[http://code.google.com/p/jsdoc-toolkit/|Google Code "jsdoc-toolkit. A documentation generator for JavaScript"]].
    *The legacy [[http://code.google.com/p/jsdoc/|Google Code "jsdoc. JSDoc is an automatic documentation generator for JavaScript"]] -> JSDoc V.2.
    *<del>[[http://jsdoc.sourceforge.net/|SourceForge "JSDoc"]]</del>, <del>[[http://www.sourceforge.net/projects/jsdoc|SourceForge "JSDoc"]]</del>.
  *[[http://en.wikipedia.org/wiki/JSDoc|EN.Wikipedia "JSDoc"]].
== JSDuck ==
 *[[http://www.github.com/senchalabs/jsduck|GitHub "JSDuck"]].
== ScriptDoc ( SDOC ) ==
  *[[http://wiki.appcelerator.org/display/guides2/ScriptDoc+%28SDOC%29+2.0+Specification|Appcelerator Inc. "ScriptDoc (SDOC) 2.0 Specification"]] for Javascript.
== YUIDoc ==
  *[[http://yui.github.io/yuidoc/|GitHub "YUIDoc - JavaScript Documentation Tool"]].
=== Markdown Markup Language ===
  *See [[revision.html|Revision Control & Revision Control Systems (RCS), Source Code Version Control Systems ( SCVCS, VCS, CVS ), Software Configuration Management ( SCM )]], "Github Gist".
=== Microsoft Windows & .NET ===
== NDoc ==
  *The free Open Source "NDoc Code Documentation Generator for .NET" ( [[http://ndoc.sourceforge.net/|Sourceforge "NDoc"]], [[http://www.sourceforge.net/projects/ndoc|Sourceforge "NDoc"]] ).
== VBCommenter ==
  *The free Open Source [[http://code.msdn.microsoft.com/VBCommenter|VBCommenter]] for Visual Basic .NET.
=== Natural Docs ===
  *[[http://www.naturaldocs.org/|Natural Docs]].
  *[[http://www.naturaldocs.org/languages.html|Natural Docs "Language Support"]] - "C/C++, Java, PHP, Python, PL/SQL, Visual Basic, Pascal/Delphi, Ada, JavaScript, Ruby, Tcl, ColdFusion, Assembly, Fortran (free-format only), R, Makefiles, Plain Text".
=== phpDocumentator ===
  *[[http://www.phpdoc.org/|phpDocumentator]] - "A tool with which it is possible to generate documentation from your PHP source code".
=== Python Documentation Generators ===
  *See [[python04.html|Python 4/7 - Pro & Contra]], section "Pythonic Documentation Tools".
  *Doxygen, with input filters for Python -> see on this page.
=== ROBODoc ===
  *[[http://rfsber.home.xs4all.nl/Robo/|Frans Slothouber "Robo"]], [[http://www.github.com/gumpu/ROBODoc|GitHub "ROBODoc"]], [[http://robodoc.sourceforge.net/|SourceForge "ROBODoc"]], [[http://www.sourceforge.net/projects/robodoc/|SourceForge "ROBODoc"]] - "A documentation tool. It extracts the documentation from your source code and formats it in HTML, RTF, TeX, XML DocBook (PDF), or ASCII. Works with C, C++, Fortran, Perl, Scripts, Assembler, Tcl, Basic, and any language that supports remarks", "Works with C, C++, Fortran, Perl, shell scripts, Assembler, DCL, DB/C, Tcl/Tk, Forth, Lisp, COBOL, Occam, Basic, HTML, Clarion, and any other language that supports remarks".
=== reStructuredText ( reST ) ===
  *See [[python04.html|Python 4/7 - Pro & Contra]], section "Pythonic Documentation Tools".
=== Sandcastle Documentation Compilers ===
  *[[http://www.sandcastledocs.com/|SandcastleDocs.com]].
  *[[http://blogs.msdn.com/sandcastle/|MSDN Blog "Sandcastle"]].
  *[[http://sandcastle.codeplex.com/|Codeplex "Sandcastle - Documentation Compiler for Managed Class"]].
==== Documentation Formats & Documentation Tools for Software Projects ====
  *Text files formatted in "ReST", "ReStructured Text", format.
    *[[http://docutils.sourceforge.net/|Sourceforge "Docutils: Documentation Utilities. Written in Python, for General- and Special-Purpose Use"]], [[http://www.sourceforge.net/projects/docutils|Sourceforge "Docutils: Documentation Utilities"]] - "Docutils is an open-source text processing system for processing plaintext documentation into useful formats, such as HTML or LaTeX".
  *Dependency graph.
    *[[http://en.wikipedia.org/wiki/Dependency_graph|EN.Wikipedia "Dependency graph"]].
    *[[http://doxygen.sourceforge.net/|Sourceforge "Doxygen"]] has built-in support to generate inheritance diagrams for C++ classes. Doxygen can use the "dot" tool from [[http://www.graphviz.org/|graphviz]] to generate more advanced diagrams and graphs".
      *Example: [[http://asf.atmel.com/docs/2.6.1/common/services/calendar/unit_tests/atxmega128a1-xplain/doxygen/html/a00058.html|Atmel Corporation "Calendar service unit tests on Xplain", "unit_tests.c File Reference"]].
    *Software tools to create dependency graphs: See [[vrml.html|Virtual Reality & Graphics]], "Free Graph Visualization and Manipulation Software".
===== Software Application Description Formats  =====
  *[[http://pad.asp-software.org/|Association of Software Professionals "Portable Application Description (PAD)"]] - "PAD is the Portable Application Description, and it helps authors provide product descriptions and specifications to online sources in a standard way, using a standard data format that will allow webmasters and program librarians to automate program listings".
===== Books =====
  *Book [[http://www.amazon.de/exec/obidos/ASIN/3446420088/hemmerling-21|Gernot Starke: "Effektive Software-Architekturen: Ein praktischer Leitfaden"]].
===== Resources =====
  *[[http://www.stack.nl/~dimitri/doxygen/links.html|Doxygen - Other non-commercial documentation tools, Other commercial documentation tools]].
  *[[http://forum.fachinformatiker.de/java/35419-javadoc-prinzip-bloss-fuer-anderes-sprachen.html|Fachinformatiker.de: "javaDoc Prinzip bloß auf für anderes Sprachen"]].
  *[[http://devdocs.magento.com/guides/v2.0/coding-standards/docblock-standard-javascript.html|Magento Developer Documentation "JavaScript DocBlock standard"]].
  *[[http://www.stackoverflow.com/questions/669698/what-options-are-available-for-documenting-your-javascript-code|StackOverflow "What options are available for documenting your Javascript code?"]].
  *[[http://en.wikipedia.org/wiki/Comparison_of_documentation_generators|EN.Wikipedia: "Comparison of documentation generators"]].
  *[[http://en.wikipedia.org/wiki/Markup_language|EN.Wikipedia "Markup language"]], [[http://de.wikipedia.org/wiki/Auszeichnungssprache|DE.Wikipedia "Auszeichnungssprache"]].
===== Forums, Newsgroups =====
  *[[http://groups.google.com/group/jsdoc-users|Google Groups "JSDoc Users"]].
{{tag>software documentation "software documentation generator" generator}}

<footnote_navi_en>