Standard interface documentation

From Wikipedia, the free encyclopedia

There are very few or no other articles that link to this one.
Please help introduce links in articles on related topics. After links have been created, remove this message.
This article has been tagged since November 2006.

This article (or section) may need to be wikified to meet Wikipedia's quality standards.
Please help improve this article, especially its section layout, and relevant internal links. (help)
This article has been tagged since October 2006.

This article may require cleanup to meet Wikipedia's quality standards.
Please discuss this issue on the talk page or replace this tag with a more specific message.
This article has been tagged since March 2006.

Standard interface documentation refers to how source code is documented. This article will provide information on documenting code for the Java and the Microsoft .NET environments. For all other languages, configuration files, and XML files, please follow the associated language-specified format for documentation.

It is also noted that all source code developed with DoD funding must be internally documented.

[edit] Environments

[edit] Java

JavaDoc parses special tags when they are embedded within a Java doc comment. These doc tags enable you to autogenerate a complete, well-formatted API Application Programming Interface. A special type of interface that specifies the calling conventions with which one component may access the resources and services provided by another component. APIs are defined by sets of procedures or function-invocation specifications. An API is a special case of an interface. from your source code. The tags start with an "at" sign (@) and are case-sensitive; an “a” is different from an “A.”

A tag must start at the beginning of a line, after any leading spaces and an optional asterisk, or it will be treated as normal text. By convention, group tags with the same name together. For example, put all @see tags together.

For information about tags that might appear in future releases of Java, see http://java.sun.com/products/jdk/javadoc/proposed-tags.html

[edit] Microsoft .Net

C, C++, IDL You can use several open-source tools to generate Javadoc-like documents for the C/C++ environment. A few of them are listed here.

Doxygen: A Javadoc-like documentation system for C++, C, Java, and IDL. Runs on POSIX and Windows. This can be found at http://sourceforge.net/projects/doxygen or http://www.stack.nl/~dimitri/doxygen/download.html.
DOC++: A Javadoc system for C, C++, IDL, and Java that generates TeX output for high-quality hard copy and HTML output for sophisticated online documentation.

Requires flex 2.5 (fast lexical analyzer generator) or higher. DOC++ is at http://docpp.sourceforge.net, and flex is available at: http://www.gnu.org/directory/flex.html.