Fix file documentation

35 files changed, 82 insertions, 48 deletions

diff --git a/doc/layout.xml b/doc/layout.xml
index 4744245..2995c0e 100644
--- a/doc/layout.xml
+++ b/doc/layout.xml
@@ -108,6 +108,7 @@
   <!-- Layout definition for a file page -->
   <file>
     <briefdescription visible="yes"/>
+    <detaileddescription title=""/>
     <includes visible="$SHOW_INCLUDE_FILES"/>
     <includegraph visible="$INCLUDE_GRAPH"/>
     <includedbygraph visible="$INCLUDED_BY_GRAPH"/>
@@ -123,7 +124,6 @@
       <variables title=""/>
       <membergroups visible="yes"/>
     </memberdecl>
-    <detaileddescription title=""/>
     <memberdef>
       <inlineclasses title=""/>
       <defines title=""/>
diff --git a/examples/pugl_cairo_demo.c b/examples/pugl_cairo_demo.c
index 483446f..5f8dad9 100644
--- a/examples/pugl_cairo_demo.c
+++ b/examples/pugl_cairo_demo.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_cairo_demo.c An example of drawing with Cairo.
+   @file pugl_cairo_demo.c
+   @brief An example of drawing with Cairo.
 */
 
 #include "demo_utils.h"
diff --git a/examples/pugl_cxx_demo.cpp b/examples/pugl_cxx_demo.cpp
index 6a7538f..2fa7d8b 100644
--- a/examples/pugl_cxx_demo.cpp
+++ b/examples/pugl_cxx_demo.cpp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_cxx_demo.cpp A simple demo of the Pugl C++ API.
+   @file pugl_cxx_demo.cpp
+   @brief A simple demo of the Pugl C++ API.
 */
 
 #include "cube_view.h"
diff --git a/examples/pugl_embed_demo.c b/examples/pugl_embed_demo.c
index 3a7b051..40c8e54 100644
--- a/examples/pugl_embed_demo.c
+++ b/examples/pugl_embed_demo.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_embed_demo.c An example of embedding a view in another.
+   @file pugl_embed_demo.c
+   @brief An example of embedding a view in another.
 */
 
 #include "cube_view.h"
diff --git a/examples/pugl_print_events.c b/examples/pugl_print_events.c
index 52b58c4..e2661e0 100644
--- a/examples/pugl_print_events.c
+++ b/examples/pugl_print_events.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_print_events.c A utility program that prints view events.
+   @file pugl_print_events.c
+   @brief A utility program that prints view events.
 */
 
 #include "test/test_utils.h"
diff --git a/examples/pugl_shader_demo.c b/examples/pugl_shader_demo.c
index ac5fe84..ecad8ae 100644
--- a/examples/pugl_shader_demo.c
+++ b/examples/pugl_shader_demo.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_shader_demo.c An example of drawing with OpenGL 3/4.
+   @file pugl_shader_demo.c
+   @brief An example of drawing with OpenGL 3/4.
 
    This is an example of using OpenGL for pixel-perfect 2D drawing.  It uses
    pixel coordinates for positions and sizes so that things work roughly like a
diff --git a/examples/pugl_window_demo.c b/examples/pugl_window_demo.c
index 3a0dc51..4d5c4ad 100644
--- a/examples/pugl_window_demo.c
+++ b/examples/pugl_window_demo.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_window_demo.c A demonstration of multiple Pugl windows.
+   @file pugl_window_demo.c
+   @brief A demonstration of multiple Pugl windows.
 */
 
 #include "cube_view.h"
diff --git a/examples/rects.h b/examples/rects.h
index aca0256..ed518f4 100644
--- a/examples/rects.h
+++ b/examples/rects.h
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file rects.h Utilities for rectangle animation demos.
+   @file rects.h
+   @brief Utilities for rectangle animation demos.
 
    This file contains common definitions for demos that show an animation of
    many 2D rectangles.
diff --git a/pugl/detail/implementation.c b/pugl/detail/implementation.c
index ee9b242..57d6f37 100644
--- a/pugl/detail/implementation.c
+++ b/pugl/detail/implementation.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file implementation.c Platform-independent implementation.
+   @file implementation.c
+   @brief Platform-independent implementation.
 */
 
 #include "pugl/detail/implementation.h"
diff --git a/pugl/detail/implementation.h b/pugl/detail/implementation.h
index bcecd85..d56024a 100644
--- a/pugl/detail/implementation.h
+++ b/pugl/detail/implementation.h
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file implementation.h Shared declarations for implementation.
+   @file implementation.h
+   @brief Shared declarations for implementation.
 */
 
 #ifndef PUGL_DETAIL_IMPLEMENTATION_H
diff --git a/pugl/detail/mac.h b/pugl/detail/mac.h
index 2243337..f650577 100644
--- a/pugl/detail/mac.h
+++ b/pugl/detail/mac.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
   Copyright 2017 Hanspeter Portner <dev@open-music-kontrollers.ch>
 
   Permission to use, copy, modify, and/or distribute this software for any
@@ -16,7 +16,8 @@
 */
 
 /**
-   @file mac.h Shared definitions for MacOS implementation.
+   @file mac.h
+   @brief Shared definitions for MacOS implementation.
 */
 
 #include "pugl/pugl.h"
diff --git a/pugl/detail/mac.m b/pugl/detail/mac.m
index 0b26cb7..bf3ad65 100644
--- a/pugl/detail/mac.m
+++ b/pugl/detail/mac.m
@@ -16,7 +16,8 @@
 */
 
 /**
-   @file mac.m MacOS implementation.
+   @file mac.m
+   @brief MacOS implementation.
 */
 
 #define GL_SILENCE_DEPRECATION 1
diff --git a/pugl/detail/mac_cairo.m b/pugl/detail/mac_cairo.m
index ccce14e..2949586 100644
--- a/pugl/detail/mac_cairo.m
+++ b/pugl/detail/mac_cairo.m
@@ -1,5 +1,5 @@
 /*
-  Copyright 2019 David Robillard <http://drobilla.net>
+  Copyright 2019-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file mac_cairo.m Cairo graphics backend for MacOS.
+   @file mac_cairo.m
+   @brief Cairo graphics backend for MacOS.
 */
 
 #include "pugl/detail/implementation.h"
diff --git a/pugl/detail/mac_gl.m b/pugl/detail/mac_gl.m
index 3d55056..209d90c 100644
--- a/pugl/detail/mac_gl.m
+++ b/pugl/detail/mac_gl.m
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file mac_gl.m OpenGL graphics backend for MacOS.
+   @file mac_gl.m
+   @brief OpenGL graphics backend for MacOS.
 */
 
 #include "pugl/detail/implementation.h"
diff --git a/pugl/detail/mac_stub.m b/pugl/detail/mac_stub.m
index 71a54b8..aa2ac55 100644
--- a/pugl/detail/mac_stub.m
+++ b/pugl/detail/mac_stub.m
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file mac_stub.m Stub graphics backend for MacOS.
+   @file mac_stub.m
+   @brief Stub graphics backend for MacOS.
 */
 
 #include "pugl/detail/implementation.h"
diff --git a/pugl/detail/types.h b/pugl/detail/types.h
index eb450e1..5a4c84d 100644
--- a/pugl/detail/types.h
+++ b/pugl/detail/types.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file types.h Shared internal type definitions.
+   @file types.h
+   @brief Shared internal type definitions.
 */
 
 #ifndef PUGL_DETAIL_TYPES_H
diff --git a/pugl/detail/win.c b/pugl/detail/win.c
index cb9a69c..f73a432 100644
--- a/pugl/detail/win.c
+++ b/pugl/detail/win.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file win.c Windows implementation.
+   @file win.c
+   @brief Windows implementation.
 */
 
 #include "pugl/detail/win.h"
diff --git a/pugl/detail/win.h b/pugl/detail/win.h
index 241ea24..4cba95c 100644
--- a/pugl/detail/win.h
+++ b/pugl/detail/win.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file win.h Shared definitions for Windows implementation.
+   @file win.h
+   @brief Shared definitions for Windows implementation.
 */
 
 #include "pugl/detail/implementation.h"
diff --git a/pugl/detail/win_cairo.c b/pugl/detail/win_cairo.c
index a8b371f..d171129 100644
--- a/pugl/detail/win_cairo.c
+++ b/pugl/detail/win_cairo.c
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file win_cairo.c Cairo graphics backend for Windows.
+   @file win_cairo.c
+   @brief Cairo graphics backend for Windows.
 */
 
 #include "pugl/detail/types.h"
diff --git a/pugl/detail/win_gl.c b/pugl/detail/win_gl.c
index f5acfd6..9dfd129 100644
--- a/pugl/detail/win_gl.c
+++ b/pugl/detail/win_gl.c
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file win_gl.c OpenGL graphics backend for Windows.
+   @file win_gl.c
+   @brief OpenGL graphics backend for Windows.
 */
 
 #include "pugl/detail/types.h"
diff --git a/pugl/detail/x11.c b/pugl/detail/x11.c
index e3fb264..001540b 100644
--- a/pugl/detail/x11.c
+++ b/pugl/detail/x11.c
@@ -17,7 +17,8 @@
 */
 
 /**
-   @file x11.c X11 implementation.
+   @file x11.c
+   @brief X11 implementation.
 */
 
 #define _POSIX_C_SOURCE 199309L
diff --git a/pugl/detail/x11.h b/pugl/detail/x11.h
index 6b7a150..61149b9 100644
--- a/pugl/detail/x11.h
+++ b/pugl/detail/x11.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file x11.h Shared definitions for X11 implementation.
+   @file x11.h
+   @brief Shared definitions for X11 implementation.
 */
 
 #include "pugl/detail/types.h"
diff --git a/pugl/detail/x11_cairo.c b/pugl/detail/x11_cairo.c
index 0229d97..1661762 100644
--- a/pugl/detail/x11_cairo.c
+++ b/pugl/detail/x11_cairo.c
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file x11_cairo.c Cairo graphics backend for X11.
+   @file x11_cairo.c
+   @brief Cairo graphics backend for X11.
 */
 
 #include "pugl/detail/types.h"
diff --git a/pugl/detail/x11_gl.c b/pugl/detail/x11_gl.c
index 33a05df..7e3a69d 100644
--- a/pugl/detail/x11_gl.c
+++ b/pugl/detail/x11_gl.c
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file x11_gl.c OpenGL graphics backend for X11.
+   @file x11_gl.c
+   @brief OpenGL graphics backend for X11.
 */
 
 #include "pugl/detail/types.h"
diff --git a/pugl/gl.h b/pugl/gl.h
index 55a55c4..b28e42b 100644
--- a/pugl/gl.h
+++ b/pugl/gl.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2014 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file gl.h Portable header wrapper for gl.h.
+   @file gl.h
+   @brief Portable header wrapper for gl.h.
 
    Unfortunately, GL includes vary across platforms so this header allows for
    pure portable programs.
diff --git a/pugl/glu.h b/pugl/glu.h
index 0ade70c..70f8a4b 100644
--- a/pugl/glu.h
+++ b/pugl/glu.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2015 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file glu.h Portable header wrapper for glu.h.
+   @file glu.h
+   @brief Portable header wrapper for glu.h.
 
    Unfortunately, GL includes vary across platforms so this header allows for
    pure portable programs.
diff --git a/pugl/pugl.h b/pugl/pugl.h
index 84bfa98..3584d05 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl.h Pugl API.
+   @file pugl.h
+   @brief Pugl API.
 */
 
 #ifndef PUGL_PUGL_H
diff --git a/pugl/pugl.hpp b/pugl/pugl.hpp
index e40424a..671e649 100644
--- a/pugl/pugl.hpp
+++ b/pugl/pugl.hpp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl.hpp Pugl C++ API wrapper.
+   @file pugl.hpp
+   @brief Pugl C++ API wrapper.
 */
 
 #ifndef PUGL_PUGL_HPP
diff --git a/pugl/pugl.ipp b/pugl/pugl.ipp
index 2fdf255..ac67626 100644
--- a/pugl/pugl.ipp
+++ b/pugl/pugl.ipp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl.ipp Pugl C++ API wrapper implementation.
+   @file pugl.ipp
+   @brief Pugl C++ API wrapper implementation.
 
    This file must be included exactly once in the application.
 */
diff --git a/pugl/pugl_cairo.h b/pugl/pugl_cairo.h
index 0321d0c..0bdf58e 100644
--- a/pugl/pugl_cairo.h
+++ b/pugl/pugl_cairo.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_cairo.h Declaration of Cairo backend accessor.
+   @file pugl_cairo.h
+   @brief Declaration of Cairo backend accessor.
 */
 
 #ifndef PUGL_PUGL_CAIRO_H
diff --git a/pugl/pugl_cairo.hpp b/pugl/pugl_cairo.hpp
index f31201e..588f989 100644
--- a/pugl/pugl_cairo.hpp
+++ b/pugl/pugl_cairo.hpp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_cairo.hpp Declaration of Cairo backend accessor for C++.
+   @file pugl_cairo.hpp
+   @brief Declaration of Cairo backend accessor for C++.
 */
 
 #ifndef PUGL_PUGL_CAIRO_HPP
diff --git a/pugl/pugl_gl.h b/pugl/pugl_gl.h
index 3257bdf..f1b398d 100644
--- a/pugl/pugl_gl.h
+++ b/pugl/pugl_gl.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2012-2019 David Robillard <http://drobilla.net>
+  Copyright 2012-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_gl.h OpenGL-specific API.
+   @file pugl_gl.h
+   @brief OpenGL-specific API.
 */
 
 #ifndef PUGL_PUGL_GL_H
diff --git a/pugl/pugl_gl.hpp b/pugl/pugl_gl.hpp
index ae618ec..3d27a4a 100644
--- a/pugl/pugl_gl.hpp
+++ b/pugl/pugl_gl.hpp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_gl.hpp OpenGL-specific C++ API.
+   @file pugl_gl.hpp
+   @brief OpenGL-specific C++ API.
 */
 
 #ifndef PUGL_PUGL_GL_HPP
diff --git a/pugl/pugl_stub.h b/pugl/pugl_stub.h
index fa89552..d1c5c92 100644
--- a/pugl/pugl_stub.h
+++ b/pugl/pugl_stub.h
@@ -1,5 +1,5 @@
 /*
-  Copyright 2019 David Robillard <http://drobilla.net>
+  Copyright 2019-2020 David Robillard <http://drobilla.net>
 
   Permission to use, copy, modify, and/or distribute this software for any
   purpose with or without fee is hereby granted, provided that the above
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_stub.h Stub backend functions and accessor declaration.
+   @file pugl_stub.h
+   @brief Stub backend functions and accessor declaration.
 */
 
 #ifndef PUGL_PUGL_STUB_H
diff --git a/pugl/pugl_stub.hpp b/pugl/pugl_stub.hpp
index 7e544ee..64f40d0 100644
--- a/pugl/pugl_stub.hpp
+++ b/pugl/pugl_stub.hpp
@@ -15,7 +15,8 @@
 */
 
 /**
-   @file pugl_stub.hpp Declaration of Stub backend accessor for C++.
+   @file pugl_stub.hpp
+   @brief Declaration of Stub backend accessor for C++.
 */
 
 #ifndef PUGL_PUGL_STUB_HPP