Release-1.5.4-20080101

1 files changed, 30 insertions, 4 deletions

diff --git a/doc/docblocks.doc b/doc/docblocks.doc
index 9ed876e..5ebdf7b 100644
--- a/doc/docblocks.doc
+++ b/doc/docblocks.doc
@@ -2,7 +2,7 @@
  *
  * 
  *
- * Copyright (C) 1997-2007 by Dimitri van Heesch.
+ * Copyright (C) 1997-2008 by Dimitri van Heesch.
  *
  * Permission to use, copy, modify, and distribute this software and its
  * documentation under the terms of the GNU General Public License is hereby 
@@ -20,9 +20,9 @@
 
 A special documentation block is a C or C++ style comment block with some 
 additional markings, so doxygen knows it is a piece of documentation that
-needs to end up in the generated documentation. For Python code there is
-a different comment convention, which can be found in section 
-\ref pythonblocks
+needs to end up in the generated documentation. For Python and VHDL
+code there are a different comment conventions, which can be found in section 
+\ref pythonblocks and \ref vhdlblocks respectively.
 
 For each code item there are two (or in some cases three) types of descriptions, 
 which together form the documentation: a \e brief description and \e detailed
@@ -414,4 +414,30 @@ Go to the <a href="lists.html">next</a> section or return to the
  <a href="index.html">index</a>.
 \endhtmlonly
 
+\section vhdlblocks Special documentation blocks in VHDL
+
+For VHDL a comment normally start with "--". Doxygen will extract comments
+starting with "--!". There are only two types of comment blocks in VHDL;
+a one line --! comment representing a brief description, and a multiline
+--! comment (where the --! prefix is repeated for each line) representing
+a detailed description.
+
+Comments are always located in front of the item that is being documented
+with one exception: for ports the comment can also be after the item
+and is then treated as a brief description for the port.
+
+Here is an example VHDL file with doxygen comments:
+
+\include  mux.vhdl
+ \htmlonly
+ Click <a href="$(DOXYGEN_DOCDIR)/examples/mux/html/index.html">here</a>
+ for the corresponding HTML documentation that is generated by doxygen.
+ \endhtmlonly
+
+To get proper looking output you need to set
+\ref cfg_optimize_output_vhdl "OPTIMIZE_OUTPUT_VHDL" to \c YES in the
+config file. This will also affect a number of other settings. When they
+were not already set correctly doxygen will produce a warning telling which
+settings where overruled.
+
 */