From a4c6c18b3dc3ed11b3aca19df37ef094a19fe025 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Tue, 9 May 2023 22:36:41 +0200 Subject: [PATCH] Fix doxygen doc generation and document platform specific files Pure platform specific files like 'src/*_win32.cxx' are excluded from doxygen processing and don't need doxygen specific guard macros. Document this fact prominently at the beginning of each file. Fix exclude patterns and remove duplicates from Doxyfile.in. --- documentation/Doxyfile.in | 28 ++++++++++++---------------- src/Fl_get_key_mac.cxx | 5 ++++- src/Fl_get_key_win32.cxx | 5 ++++- src/Fl_win32.cxx | 7 +++---- src/Fl_x.cxx | 5 ++--- src/fl_dnd_win32.cxx | 5 ++++- src/fl_dnd_x.cxx | 5 ++++- 7 files changed, 33 insertions(+), 27 deletions(-) diff --git a/documentation/Doxyfile.in b/documentation/Doxyfile.in index 6f3975464..57e49934d 100644 --- a/documentation/Doxyfile.in +++ b/documentation/Doxyfile.in @@ -614,12 +614,6 @@ RECURSIVE = YES # subdirectory from a directory tree whose root is specified with the INPUT tag. EXCLUDE = @FLTK_SOURCE_DIR@/src/drivers/ -EXCLUDE += @FLTK_SOURCE_DIR@/src/fl_dnd_win32.cxx -EXCLUDE += @FLTK_SOURCE_DIR@/src/fl_dnd_x.cxx -EXCLUDE += @FLTK_SOURCE_DIR@/src/fl_font_mac.cxx -EXCLUDE += @FLTK_SOURCE_DIR@/src/fl_font_win32.cxx -EXCLUDE += @FLTK_SOURCE_DIR@/src/Fl_get_key_mac.cxx -EXCLUDE += @FLTK_SOURCE_DIR@/src/Fl_get_key_win32.cxx # The EXCLUDE_SYMLINKS tag can be used select whether or not files or # directories that are symbolic links (a Unix filesystem feature) are excluded @@ -633,15 +627,17 @@ EXCLUDE_SYMLINKS = NO # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = @FLTK_SOURCE_DIR@/src/*_win32.cxx -EXCLUDE_PATTERNS += @FLTK_SOURCE_DIR@/src/*_mac.cxx -EXCLUDE_PATTERNS += @FLTK_SOURCE_DIR@/src/*_x.cxx +# Exclude pure platform specific source files -# Exclude Wayland specific files that are generated in the source tree -# by configure + make +EXCLUDE_PATTERNS = */src/*_win32.cxx +EXCLUDE_PATTERNS += */src/*_mac.cxx +EXCLUDE_PATTERNS += */src/*_x.cxx -EXCLUDE_PATTERNS += @FLTK_SOURCE_DIR@/src/xdg* -EXCLUDE_PATTERNS += @FLTK_SOURCE_DIR@/src/text-input* +# Exclude Wayland specific files generated in the source tree +# by configure + make (but not by CMake) + +EXCLUDE_PATTERNS += */src/xdg* +EXCLUDE_PATTERNS += */src/text-input* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the @@ -655,9 +651,9 @@ EXCLUDE_SYMBOLS = # directories that contain example code fragments that are included (see # the \include command). -EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/../test \ - @CMAKE_CURRENT_SOURCE_DIR@/../examples \ - @CMAKE_CURRENT_BINARY_DIR@ @CMAKE_CURRENT_SOURCE_DIR@ +EXAMPLE_PATH = @CMAKE_CURRENT_SOURCE_DIR@/../test \ + @CMAKE_CURRENT_SOURCE_DIR@/../examples \ + @CMAKE_CURRENT_BINARY_DIR@ @CMAKE_CURRENT_SOURCE_DIR@ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp diff --git a/src/Fl_get_key_mac.cxx b/src/Fl_get_key_mac.cxx index c950d439e..ef5ef1ae1 100644 --- a/src/Fl_get_key_mac.cxx +++ b/src/Fl_get_key_mac.cxx @@ -1,7 +1,7 @@ // // MacOS keyboard state routines for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2018 by Bill Spitzak and others. +// Copyright 1998-2023 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -14,6 +14,9 @@ // https://www.fltk.org/bugs.php // +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). + // Return the current state of a key. Keys are named by fltk symbols, // which are actually X keysyms. So this has to translate to macOS // symbols. diff --git a/src/Fl_get_key_win32.cxx b/src/Fl_get_key_win32.cxx index 590df0ff5..cb844722d 100644 --- a/src/Fl_get_key_win32.cxx +++ b/src/Fl_get_key_win32.cxx @@ -1,7 +1,7 @@ // // Windows keyboard state routines for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2018 by Bill Spitzak and others. +// Copyright 1998-2023 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -14,6 +14,9 @@ // https://www.fltk.org/bugs.php // +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). + // Return the current state of a key. Keys are named by fltk symbols, // which are actually X keysyms. So this has to translate to Windows // VK_x symbols. diff --git a/src/Fl_win32.cxx b/src/Fl_win32.cxx index 0837f45b4..8579e0ccd 100644 --- a/src/Fl_win32.cxx +++ b/src/Fl_win32.cxx @@ -14,12 +14,13 @@ // https://www.fltk.org/bugs.php // +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). + // This file contains Windows-specific code for FLTK which is always linked // in. Search other files for "_WIN32" or filenames ending in _win32.cxx // for other system-specific code. -#if defined(_WIN32) && !defined(FL_DOXYGEN) - /* We require Windows 2000 features (e.g. VK definitions) */ # if !defined(WINVER) || (WINVER < 0x0500) # ifdef WINVER @@ -2741,5 +2742,3 @@ void Fl_WinAPI_Window_Driver::capture_titlebar_and_borders(Fl_RGB_Image *&top, F fl_graphics_driver->gc(save_gc); Fl_Surface_Device::pop_current(); } - -#endif // defined(_WIN32) and !defined(FL_DOXYGEN) diff --git a/src/Fl_x.cxx b/src/Fl_x.cxx index 67f9df744..6922ac819 100644 --- a/src/Fl_x.cxx +++ b/src/Fl_x.cxx @@ -14,7 +14,8 @@ // https://www.fltk.org/bugs.php // -#if !defined(FL_DOXYGEN) +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). # ifndef FLTK_CONSOLIDATE_MOTION # define FLTK_CONSOLIDATE_MOTION 0 @@ -3026,5 +3027,3 @@ void Fl_X11_Window_Driver::show() { XMapRaised(fl_display, fl_xid(pWindow)); } } - -#endif // !defined(FL_DOXYGEN) diff --git a/src/fl_dnd_win32.cxx b/src/fl_dnd_win32.cxx index 9e69c290a..abaa588cc 100644 --- a/src/fl_dnd_win32.cxx +++ b/src/fl_dnd_win32.cxx @@ -1,7 +1,7 @@ // // Drag & Drop code for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2022 by Bill Spitzak and others. +// Copyright 1998-2023 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -14,6 +14,9 @@ // https://www.fltk.org/bugs.php // +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). + // This file contains Windows-specific code for FLTK which is always linked // in. Search other files for "_WIN32" or filenames ending in _win32.cxx // for other system-specific code. diff --git a/src/fl_dnd_x.cxx b/src/fl_dnd_x.cxx index 982ed65dd..f48ac599e 100644 --- a/src/fl_dnd_x.cxx +++ b/src/fl_dnd_x.cxx @@ -1,7 +1,7 @@ // // Drag & Drop code for the Fast Light Tool Kit (FLTK). // -// Copyright 1998-2021 by Bill Spitzak and others. +// Copyright 1998-2023 by Bill Spitzak and others. // // This library is free software. Distribution and use rights are outlined in // the file "COPYING" which should have been included with this file. If this @@ -14,6 +14,9 @@ // https://www.fltk.org/bugs.php // +// Note: this file contains platform specific code and will therefore +// not be processed by doxygen (see Doxyfile.in). + #include #include #include