Merge branch 'bug734099'

doc/commands.doc

@@ -2356,6 +2356,20 @@ Commands for visual enhancements
   \endcode
 \endverbatim
 
+  If the contents of the code block are in a language that doxygen cannot parse, doxygen
+  will just show the output as-is. You can make this explicit using .unparsed, or by
+  giving some other extension that doxygen doesn't support, e.g.
+
+\verbatim
+  \code{.unparsed}
+  Show this as-is please
+  \endcode
+
+  \code{.sh}
+  echo "This is a shell script"
+  \endcode
+\endverbatim
+
   \sa section \ref cmdendcode "\\endcode" and section \ref cmdverbatim "\\verbatim".
 
 <hr>

doc/docblocks.doc

@@ -371,7 +371,7 @@ typedef, enum or preprocessor definition you must first document the file
 that contains it (usually this will be a header file, because that file 
 contains the information that is exported to other source files).
 
-Let's repeat that, because it is often overlooked:
+@attention Let's repeat that, because it is often overlooked:
 to document global objects (functions, typedefs, enum, macros, etc), you
 <em>must</em> document the file in which they are defined. In other words, 
 there <em>must</em> at least be a \verbatim /*! \file */ \endverbatim
@@ -395,6 +395,23 @@ using structural commands:
  in comment blocks which are place in front of a function. This is clearly
  a case where the \\fn command is redundant and will only lead to problems.
 
+ When you place a comment block in a file with one of the following extensions
+ `.dox`, `.txt`, or `.doc` then doxygen will hide this file from the file list.
+
+ If you have a file that doxygen cannot parse but still would like to document it,
+ you can show it as-is using \ref cmdverbinclude "\\verbinclude", e.g.
+
+\verbatim
+/*! \file myscript.sh
+ *  Look at this nice script:
+ *  \verbinclude myscript.sh
+ */
+\endverbatim
+
+Make sure that the script is explicitly listed in the \ref cfg_input "INPUT" or
+that \ref cfg_file_patterns "FILE_PATTERNS" includes the `.sh` extention and the
+the script can be found in the path set via \ref cfg_example_path "EXAMPLE_PATH".
+
 \subsection pythonblocks Comment blocks in Python
 
 For Python there is a standard way of documenting the code using 

src/doxygen.cpp

@@ -98,6 +98,7 @@
 #include "formula.h"
 #include "settings.h"
 #include "context.h"
+#include "fileparser.h"
 
 #define RECURSE_ENTRYTREE(func,var) \
   do { if (var->children()) { \
@@ -9895,7 +9896,8 @@ void initDoxygen()
   initPreprocessor();
 
   Doxygen::parserManager = new ParserManager;
-  Doxygen::parserManager->registerParser("c",            new CLanguageScanner, TRUE);
+  Doxygen::parserManager->registerDefaultParser(         new FileParser);
+  Doxygen::parserManager->registerParser("c",            new CLanguageScanner);
   Doxygen::parserManager->registerParser("python",       new PythonLanguageScanner);
   Doxygen::parserManager->registerParser("fortran",      new FortranLanguageScanner);
   Doxygen::parserManager->registerParser("fortranfree",  new FortranLanguageScannerFree);

src/fileparser.cpp

+/******************************************************************************
+ *
+ * Copyright (C) 1997-2014 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
+ * granted. No representations are made about the suitability of this software
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+
+#include "fileparser.h"
+#include "outputgen.h"
+
+void FileParser::parseCode(CodeOutputInterface &codeOutIntf,
+               const char *,     // scopeName
+               const QCString &     input,
+               SrcLangExt,       // lang
+               bool,             // isExampleBlock
+               const char *,     // exampleName
+               FileDef *,        // fileDef
+               int                  startLine,
+               int                  endLine,
+               bool,             // inlineFragment
+               MemberDef *,      // memberDef
+               bool                 showLineNumbers,
+               Definition *,     // searchCtx,
+               bool              // collectXRefs
+              )
+{
+  int lineNr = startLine!=-1 ? startLine : 1;
+  int length = input.length();
+  int i=0;
+  while (i<length && (endLine==-1 || lineNr<=endLine))
+  {
+    int j=i;
+    while (j<length && input[j]!='\n') j++;
+    QCString lineStr = input.mid(i,j-i);
+    codeOutIntf.startCodeLine(showLineNumbers);
+    if (showLineNumbers) codeOutIntf.writeLineNumber(0,0,0,lineNr);
+    codeOutIntf.codify(lineStr);
+    codeOutIntf.endCodeLine();
+    lineNr++;
+    i=j+1;
+  }
+}
+

src/fileparser.h

+/******************************************************************************
+ *
+ * Copyright (C) 1997-2014 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 
+ * granted. No representations are made about the suitability of this software 
+ * for any purpose. It is provided "as is" without express or implied warranty.
+ * See the GNU General Public License for more details.
+ *
+ * Documents produced by Doxygen are derivative works derived from the
+ * input used in their production; they are not affected by this license.
+ *
+ */
+
+#ifndef FILEPARSER_H
+#define FILEPARSER_H
+
+#include "parserintf.h"
+
+/** @brief General file parser */
+class FileParser : public ParserInterface
+{
+  public:
+    virtual ~FileParser() {}
+    void startTranslationUnit(const char *) {}
+    void finishTranslationUnit() {}
+    void parseInput(const char *, const char *,Entry *, bool, QStrList &) {}
+    bool needsPreprocessing(const QCString &) { return FALSE; }
+    void parseCode(CodeOutputInterface &codeOutIntf,
+                   const char *scopeName,
+                   const QCString &input,
+                   SrcLangExt lang,
+                   bool isExampleBlock,
+                   const char *exampleName=0,
+                   FileDef *fileDef=0,
+                   int startLine=-1,
+                   int endLine=-1,
+                   bool inlineFragment=FALSE,
+                   MemberDef *memberDef=0,
+                   bool showLineNumbers=TRUE,
+                   Definition *searchCtx=0,
+                   bool collectXRefs=TRUE
+                  );
+    void resetCodeParserState() {}
+    void parsePrototype(const char *) {}
+};
+
+
+#endif

src/libdoxygen.pro.in

@@ -50,6 +50,7 @@ HEADERS      =	arguments.h \
 		example.h \
 		filedef.h \
 		filename.h \
+		fileparser.h \
 		formula.h \
 		ftextstream.h \
 		ftvhelp.h \
@@ -146,6 +147,7 @@ SOURCES      =	arguments.cpp \
 		entry.cpp \
 		filedef.cpp \
 		filename.cpp \
+		fileparser.cpp \
 		formula.cpp \
 		ftextstream.cpp \
 		ftvhelp.cpp \

src/parserintf.h

@@ -148,17 +148,19 @@ class ParserManager
     ParserManager()
       : m_defaultParser(0) { m_parsers.setAutoDelete(TRUE); }
 
+    void registerDefaultParser(ParserInterface *parser)
+    {
+      m_defaultParser = parser;
+    }
+
     /** Registers an additional parser.
      *  @param[in] name      A symbolic name of the parser, i.e. "c",
      *                       "python", "fortran", "vhdl", ...
      *  @param[in] parser    The parser that is to be used for the
      *                       given name.
-     *  @param[in] defParser Use this parser as the default parser, used
-     *                       for unregistered file extensions.
      */
-    void registerParser(const char *name,ParserInterface *parser,bool defParser=FALSE)
+    void registerParser(const char *name,ParserInterface *parser)
     {
-      if (defParser && m_defaultParser==0) m_defaultParser=parser;
       m_parsers.insert(name,parser);
     }
 

src/util.cpp

@@ -6704,6 +6704,28 @@ void initDefaultExtensionMapping()
 {
   g_extLookup.setAutoDelete(TRUE);
   //                  extension      parser id
+  updateLanguageMapping(".dox",      "c");
+  updateLanguageMapping(".txt",      "c");
+  updateLanguageMapping(".doc",      "c");
+  updateLanguageMapping(".c",        "c");
+  updateLanguageMapping(".C",        "c");
+  updateLanguageMapping(".cc",       "c");
+  updateLanguageMapping(".CC",       "c");
+  updateLanguageMapping(".cxx",      "c");
+  updateLanguageMapping(".cpp",      "c");
+  updateLanguageMapping(".c++",      "c");
+  updateLanguageMapping(".ii",       "c");
+  updateLanguageMapping(".ixx",      "c");
+  updateLanguageMapping(".ipp",      "c");
+  updateLanguageMapping(".i++",      "c");
+  updateLanguageMapping(".inl",      "c");
+  updateLanguageMapping(".h",        "c");
+  updateLanguageMapping(".H",        "c");
+  updateLanguageMapping(".hh",       "c");
+  updateLanguageMapping(".HH",       "c");
+  updateLanguageMapping(".hxx",      "c");
+  updateLanguageMapping(".hpp",      "c");
+  updateLanguageMapping(".h++",      "c");
   updateLanguageMapping(".idl",      "idl");
   updateLanguageMapping(".ddl",      "idl");
   updateLanguageMapping(".odl",      "idl");

winbuild/Doxygen.vcproj

@@ -686,6 +686,10 @@
 				RelativePath="..\src\filename.cpp"
 				>
 			</File>
+			<File
+				RelativePath="..\src\fileparser.cpp"
+				>
+			</File>
 			<File
 				RelativePath="..\src\formula.cpp"
 				>
@@ -2382,6 +2386,10 @@
 				RelativePath="..\src\filename.h"
 				>
 			</File>
+			<File
+				RelativePath="..\src\fileparser.h"
+				>
+			</File>
 			<File
 				RelativePath="$(IntDir)\footer_html.h"
 				>