Created attachment 258905 [details] [review]
SOURCE_DEFINITION patch

Hi all,

We have a special use case of doxygen:

1. We have TCL classes which are implemented in C++.
To generate the documentation, we create a "dummy" (TCL) source file (api.tcl)
which just defines the class and the methods (with their arguments)
without implementation.

During documentation generation, the source code in the file is filtered out
Doxyfile:
    FILTER_SOURCE_FILES = YES
    FILTER_SOURCE_PATTERNS = *api.tcl="api_source_filter.sh"
with api_source_filter.sh being an empty file.

This source code is not desired in our doxygen files listing output,
nor do we want any link to the "filtered-out" source code.



This would work great if we have SOURCE_BROWSER = NO in our Doxyfile, but:

2. We also provide documentation for wrapper scripts for our TCL API.
This part includes (open-source) scripts and tools to ease the use of our API (described in 1.).
This documentation is listed in the Files section of doxygen. So we explicitly need SOURCE_BROWSER = YES in order to make this work.



Another option is to split up the documentation it 2 parts, but:

3. There are some restrictions to do this:
    * The API and TCL wrapper scripts refer to each other
    * We also have example pages which refer to the API and wrapper and vice versa.
  So the documentation MUST be in one Doxygen project.



To remove the linking to the source file in classes and class members,
we created a patch for doxygen 1.8.5 release (see attachment).
It can be controlled by the SOURCE_DEFINITION configuration item.
Linking to the source is still enabled by default.

Note that our patch does not remove the links to source code
for documentation in the Files section!

Any comments or other suggestions for our change are very welcome!

If there are any other suggestions for our flexible documentation,
please let us know!

With best regards,
Tom.