From 1c97cdb115ea3b339b334135d1e1de1fab6e47aa Mon Sep 17 00:00:00 2001 From: James Muehlner Date: Wed, 23 Feb 2022 11:16:43 -0800 Subject: [PATCH] GUACAMOLE-1538: Autogenerate docs for new library. --- .dockerignore | 2 +- .gitignore | 2 +- Makefile.am | 19 +++--- configure.ac | 3 +- doc/libguac-terminal/Doxyfile.in | 59 +++++++++++++++++++ doc/{ => libguac}/Doxyfile.in | 4 +- src/terminal/Makefile.am | 10 ++-- .../{color-scheme.c => color_scheme.c} | 2 +- .../{named-colors.c => named_colors.c} | 0 src/terminal/terminal.c | 2 +- src/terminal/terminal/buffer.h | 7 +++ src/terminal/terminal/char_mappings.h | 6 ++ .../{color-scheme.h => color_scheme.h} | 6 ++ src/terminal/terminal/common.h | 6 ++ src/terminal/terminal/display.h | 6 ++ .../{named-colors.h => named_colors.h} | 6 ++ src/terminal/terminal/palette.h | 6 ++ src/terminal/terminal/scrollbar.h | 6 ++ src/terminal/terminal/select.h | 6 ++ src/terminal/terminal/terminal.h | 7 +++ src/terminal/terminal/terminal_handlers.h | 6 ++ src/terminal/terminal/types.h | 7 +++ src/terminal/terminal/typescript.h | 7 +++ src/terminal/terminal/xparsecolor.h | 6 ++ ...stdin-stream.c => terminal_stdin_stream.c} | 0 src/terminal/xparsecolor.c | 2 +- 26 files changed, 171 insertions(+), 22 deletions(-) create mode 100644 doc/libguac-terminal/Doxyfile.in rename doc/{ => libguac}/Doxyfile.in (94%) rename src/terminal/{color-scheme.c => color_scheme.c} (99%) rename src/terminal/{named-colors.c => named_colors.c} (100%) rename src/terminal/terminal/{color-scheme.h => color_scheme.h} (96%) rename src/terminal/terminal/{named-colors.h => named_colors.h} (93%) rename src/terminal/{terminal-stdin-stream.c => terminal_stdin_stream.c} (100%) diff --git a/.dockerignore b/.dockerignore index 6e106436..fcfe87b0 100644 --- a/.dockerignore +++ b/.dockerignore @@ -56,5 +56,5 @@ tests/test_* !tests/test_*.[ch] # Generated docs -doc/doxygen-output +doc/*/doxygen-output diff --git a/.gitignore b/.gitignore index 8b8022ad..e72000d8 100644 --- a/.gitignore +++ b/.gitignore @@ -44,7 +44,7 @@ configure stamp-h1 # Generated docs -doc/doxygen-output +doc/*/doxygen-output # IDE metadata nbproject/ diff --git a/Makefile.am b/Makefile.am index c75735c1..6ce3814a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -89,14 +89,15 @@ if ENABLE_GUACLOG SUBDIRS += src/guaclog endif -EXTRA_DIST = \ - .dockerignore \ - CONTRIBUTING \ - Dockerfile \ - LICENSE \ - NOTICE \ - bin/guacctl \ - doc/Doxyfile.in \ - src/guacd-docker \ +EXTRA_DIST = \ + .dockerignore \ + CONTRIBUTING \ + Dockerfile \ + LICENSE \ + NOTICE \ + bin/guacctl \ + doc/libguac/Doxyfile.in \ + doc/libguac-terminal/Doxyfile.in \ + src/guacd-docker \ util/generate-test-runner.pl diff --git a/configure.ac b/configure.ac index 54a958bc..624aae13 100644 --- a/configure.ac +++ b/configure.ac @@ -1167,7 +1167,8 @@ AM_CONDITIONAL([ENABLE_GUACLOG], [test "x${enable_guaclog}" = "xyes"]) # AC_CONFIG_FILES([Makefile - doc/Doxyfile + doc/libguac/Doxyfile + doc/libguac-terminal/Doxyfile src/common/Makefile src/common/tests/Makefile src/common-ssh/Makefile diff --git a/doc/libguac-terminal/Doxyfile.in b/doc/libguac-terminal/Doxyfile.in new file mode 100644 index 00000000..640ab48a --- /dev/null +++ b/doc/libguac-terminal/Doxyfile.in @@ -0,0 +1,59 @@ +# +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. +# + +# +# Project name / version +# + +PROJECT_NAME = libguac-terminal +PROJECT_NUMBER = @PACKAGE_VERSION@ + +# +# Warn about undocumented parameters and return values, but do not fill output +# with verbose progress info. +# + +QUIET = YES +WARN_NO_PARAMDOC = YES + +# +# Output format +# + +ALPHABETICAL_INDEX = YES +GENERATE_HTML = YES +GENERATE_LATEX = NO +OPTIMIZE_OUTPUT_FOR_C = YES +OUTPUT_DIRECTORY = doxygen-output +RECURSIVE = YES +SHOW_INCLUDE_FILES = NO + +# +# Input format +# + +CASE_SENSE_NAMES = YES +FILE_PATTERNS = *.h +STRIP_FROM_PATH = ../../src/terminal +INPUT = ../../src/terminal/terminal/ +EXCLUDE = ../../src/terminal/terminal/terminal_priv.h +JAVADOC_AUTOBRIEF = YES +TAB_SIZE = 4 +TYPEDEF_HIDES_STRUCT = YES + diff --git a/doc/Doxyfile.in b/doc/libguac/Doxyfile.in similarity index 94% rename from doc/Doxyfile.in rename to doc/libguac/Doxyfile.in index 83d54df7..5a0ae6bc 100644 --- a/doc/Doxyfile.in +++ b/doc/libguac/Doxyfile.in @@ -52,9 +52,9 @@ SHOW_INCLUDE_FILES = NO CASE_SENSE_NAMES = YES EXCLUDE_SYMBOLS = __* guac_palette* FILE_PATTERNS = *.h -INPUT = ../src/libguac/guacamole +INPUT = ../../src/libguac/guacamole JAVADOC_AUTOBRIEF = YES -STRIP_FROM_PATH = ../src/libguac +STRIP_FROM_PATH = ../../src/libguac TAB_SIZE = 4 TYPEDEF_HIDES_STRUCT = YES diff --git a/src/terminal/Makefile.am b/src/terminal/Makefile.am index 1219e968..52cc13dd 100644 --- a/src/terminal/Makefile.am +++ b/src/terminal/Makefile.am @@ -37,9 +37,9 @@ libguac_terminalinc_HEADERS = \ terminal/buffer.h \ terminal/char_mappings.h \ terminal/common.h \ - terminal/color-scheme.h \ + terminal/color_scheme.h \ terminal/display.h \ - terminal/named-colors.h \ + terminal/named_colors.h \ terminal/palette.h \ terminal/scrollbar.h \ terminal/select.h \ @@ -52,16 +52,16 @@ libguac_terminalinc_HEADERS = \ libguac_terminal_la_SOURCES = \ buffer.c \ char_mappings.c \ - color-scheme.c \ + color_scheme.c \ common.c \ display.c \ - named-colors.c \ + named_colors.c \ palette.c \ scrollbar.c \ select.c \ terminal.c \ terminal_handlers.c \ - terminal-stdin-stream.c \ + terminal_stdin_stream.c \ typescript.c \ xparsecolor.c diff --git a/src/terminal/color-scheme.c b/src/terminal/color_scheme.c similarity index 99% rename from src/terminal/color-scheme.c rename to src/terminal/color_scheme.c index 5df181fa..ec602e12 100644 --- a/src/terminal/color-scheme.c +++ b/src/terminal/color_scheme.c @@ -19,7 +19,7 @@ #include "config.h" -#include "terminal/color-scheme.h" +#include "terminal/color_scheme.h" #include "terminal/palette.h" #include "terminal/xparsecolor.h" diff --git a/src/terminal/named-colors.c b/src/terminal/named_colors.c similarity index 100% rename from src/terminal/named-colors.c rename to src/terminal/named_colors.c diff --git a/src/terminal/terminal.c b/src/terminal/terminal.c index c67998cc..4378a304 100644 --- a/src/terminal/terminal.c +++ b/src/terminal/terminal.c @@ -22,7 +22,7 @@ #include "common/clipboard.h" #include "common/cursor.h" #include "terminal/buffer.h" -#include "terminal/color-scheme.h" +#include "terminal/color_scheme.h" #include "terminal/common.h" #include "terminal/display.h" #include "terminal/palette.h" diff --git a/src/terminal/terminal/buffer.h b/src/terminal/terminal/buffer.h index 0e08226a..fb5c77f8 100644 --- a/src/terminal/terminal/buffer.h +++ b/src/terminal/terminal/buffer.h @@ -21,6 +21,13 @@ #ifndef _GUAC_TERMINAL_BUFFER_H #define _GUAC_TERMINAL_BUFFER_H +/** + * Data structures and functions related to the terminal buffer. + * + * @file buffer.h + */ + + #include "config.h" #include "types.h" diff --git a/src/terminal/terminal/char_mappings.h b/src/terminal/terminal/char_mappings.h index 5e0e4742..937c4147 100644 --- a/src/terminal/terminal/char_mappings.h +++ b/src/terminal/terminal/char_mappings.h @@ -21,6 +21,12 @@ #ifndef _GUAC_TERMINAL_CHAR_MAPPINGS_H #define _GUAC_TERMINAL_CHAR_MAPPINGS_H +/** + * Graphics character mapping definitions. + * + * @file char_mappings.h + */ + #include "config.h" /** diff --git a/src/terminal/terminal/color-scheme.h b/src/terminal/terminal/color_scheme.h similarity index 96% rename from src/terminal/terminal/color-scheme.h rename to src/terminal/terminal/color_scheme.h index 5417ce1c..446b9eed 100644 --- a/src/terminal/terminal/color-scheme.h +++ b/src/terminal/terminal/color_scheme.h @@ -20,6 +20,12 @@ #ifndef GUAC_TERMINAL_COLOR_SCHEME_H #define GUAC_TERMINAL_COLOR_SCHEME_H +/** + * Definitions and functions related to color scheme handling. + * + * @file color_scheme.h + */ + #include "config.h" #include "terminal/palette.h" diff --git a/src/terminal/terminal/common.h b/src/terminal/terminal/common.h index ad059a87..5ca8f37b 100644 --- a/src/terminal/terminal/common.h +++ b/src/terminal/terminal/common.h @@ -21,6 +21,12 @@ #ifndef _GUAC_TERMINAL_COMMON_H #define _GUAC_TERMINAL_COMMON_H +/** + * Miscellaneous terminal function definitions. + * + * @file common.h + */ + #include "config.h" #include "types.h" diff --git a/src/terminal/terminal/display.h b/src/terminal/terminal/display.h index 5377cb14..456343da 100644 --- a/src/terminal/terminal/display.h +++ b/src/terminal/terminal/display.h @@ -21,6 +21,12 @@ #ifndef _GUAC_TERMINAL_DISPLAY_H #define _GUAC_TERMINAL_DISPLAY_H +/** + * Structures and function definitions related to the graphical display. + * + * @file display.h + */ + #include "config.h" #include "common/surface.h" diff --git a/src/terminal/terminal/named-colors.h b/src/terminal/terminal/named_colors.h similarity index 93% rename from src/terminal/terminal/named-colors.h rename to src/terminal/terminal/named_colors.h index 675bf124..615d6978 100644 --- a/src/terminal/terminal/named-colors.h +++ b/src/terminal/terminal/named_colors.h @@ -20,6 +20,12 @@ #ifndef GUAC_TERMINAL_NAMED_COLORS_H #define GUAC_TERMINAL_NAMED_COLORS_H +/** + * Function definitions for operating on individual terminal colors. + * + * @file named_colors.h + */ + #include "config.h" #include "terminal/palette.h" diff --git a/src/terminal/terminal/palette.h b/src/terminal/terminal/palette.h index b1524b5a..88a6b923 100644 --- a/src/terminal/terminal/palette.h +++ b/src/terminal/terminal/palette.h @@ -20,6 +20,12 @@ #ifndef GUAC_TERMINAL_PALETTE_H #define GUAC_TERMINAL_PALETTE_H +/** + * Constants, structures, and function definitions related to the terminal color pallate. + * + * @file palette.h + */ + #include "config.h" #include diff --git a/src/terminal/terminal/scrollbar.h b/src/terminal/terminal/scrollbar.h index bf0da873..9e6c5ebc 100644 --- a/src/terminal/terminal/scrollbar.h +++ b/src/terminal/terminal/scrollbar.h @@ -20,6 +20,12 @@ #ifndef GUAC_TERMINAL_SCROLLBAR_H #define GUAC_TERMINAL_SCROLLBAR_H +/** + * Constants, structures, and function definitions related to the terminal scrollbar. + * + * @file scrollbar.h + */ + #include "config.h" #include diff --git a/src/terminal/terminal/select.h b/src/terminal/terminal/select.h index 1ae7d3d2..8abdd019 100644 --- a/src/terminal/terminal/select.h +++ b/src/terminal/terminal/select.h @@ -21,6 +21,12 @@ #ifndef GUAC_TERMINAL_SELECT_H #define GUAC_TERMINAL_SELECT_H +/** + * Function definitions related to selecting text withing a terminal. + * + * @file select.h + */ + #include "config.h" #include "terminal.h" diff --git a/src/terminal/terminal/terminal.h b/src/terminal/terminal/terminal.h index c78f61f4..dba68e32 100644 --- a/src/terminal/terminal/terminal.h +++ b/src/terminal/terminal/terminal.h @@ -21,6 +21,13 @@ #ifndef _GUAC_TERMINAL_H #define _GUAC_TERMINAL_H +/** + * Constants, structures, and function definitions defining the core + * functionality for the terminal library. + * + * @file terminal.h + */ + #include "config.h" #include "buffer.h" diff --git a/src/terminal/terminal/terminal_handlers.h b/src/terminal/terminal/terminal_handlers.h index 0869b19d..e293c581 100644 --- a/src/terminal/terminal/terminal_handlers.h +++ b/src/terminal/terminal/terminal_handlers.h @@ -21,6 +21,12 @@ #ifndef _GUAC_TERMINAL_HANDLERS #define _GUAC_TERMINAL_HANDLERS +/** + * Function definitions for terminal event handlers. + * + * @file terminal_handlers.h + */ + #include "config.h" #include "terminal.h" diff --git a/src/terminal/terminal/types.h b/src/terminal/terminal/types.h index 0d054f8f..fbf9c646 100644 --- a/src/terminal/terminal/types.h +++ b/src/terminal/terminal/types.h @@ -21,6 +21,13 @@ #ifndef _GUAC_TERMINAL_TYPES_H #define _GUAC_TERMINAL_TYPES_H +/** + * Structures and function definitions related to individual characters + * within the terminal. + * + * @file types.h + */ + #include "config.h" #include "palette.h" diff --git a/src/terminal/terminal/typescript.h b/src/terminal/terminal/typescript.h index 9fce9e54..9f8dff2d 100644 --- a/src/terminal/terminal/typescript.h +++ b/src/terminal/terminal/typescript.h @@ -21,6 +21,13 @@ #ifndef GUAC_TERMINAL_TYPESCRIPT_H #define GUAC_TERMINAL_TYPESCRIPT_H +/** + * Constants, structures, and function definitions related to terminal + * typescripts. + * + * @file typescript.h + */ + #include "config.h" #include diff --git a/src/terminal/terminal/xparsecolor.h b/src/terminal/terminal/xparsecolor.h index 7cb2fcaa..398de758 100644 --- a/src/terminal/terminal/xparsecolor.h +++ b/src/terminal/terminal/xparsecolor.h @@ -20,6 +20,12 @@ #ifndef GUAC_TERMINAL_XPARSECOLOR_H #define GUAC_TERMINAL_XPARSECOLOR_H +/** + * Function definitions related to handling X11 color specs. + * + * @file xparsecolor.h + */ + #include "config.h" #include "terminal/palette.h" diff --git a/src/terminal/terminal-stdin-stream.c b/src/terminal/terminal_stdin_stream.c similarity index 100% rename from src/terminal/terminal-stdin-stream.c rename to src/terminal/terminal_stdin_stream.c diff --git a/src/terminal/xparsecolor.c b/src/terminal/xparsecolor.c index 779374d8..f5432476 100644 --- a/src/terminal/xparsecolor.c +++ b/src/terminal/xparsecolor.c @@ -19,7 +19,7 @@ #include "config.h" -#include "terminal/named-colors.h" +#include "terminal/named_colors.h" #include "terminal/palette.h" #include