Merge branch 'dwrite-docs' into 'master'

Simplify generating dwrite-fonts docs

See merge request cairo/cairo!426

5 files changed, 83 insertions, 135 deletions

diff --git a/doc/public/meson.build b/doc/public/meson.build
index 31168f268..7f25ea1a9 100644
--- a/doc/public/meson.build
+++ b/doc/public/meson.build
@@ -140,6 +140,7 @@ gnome.gtkdoc('cairo',
     '--ignore-decorators=' + '|'.join(ignore_decorators),
     '--ignore-headers=' + ' '.join(ignore_headers),
   ],
+  mkdb_args: ['--source-suffixes=h,c,cpp'],
   content_files: [
     'language-bindings.xml',
   ],
diff --git a/src/meson.build b/src/meson.build
index 30de39f35..768dba143 100644
--- a/src/meson.build
+++ b/src/meson.build
@@ -180,7 +180,6 @@ cairo_feature_sources = {
     'win32/cairo-win32-font.c',
   ],
   'cairo-win32-dwrite-font': [
-    'win32/cairo-dwrite-font-public.c',
     'win32/cairo-dwrite-font.cpp',
   ],
   'cairo-gl': [
diff --git a/src/win32/cairo-dwrite-font-public.c b/src/win32/cairo-dwrite-font-public.c
deleted file mode 100644
index 9a4c6a1a1..000000000
--- a/src/win32/cairo-dwrite-font-public.c
+++ /dev/null
@@ -1,130 +0,0 @@
-/* -*- Mode: c; tab-width: 8; c-basic-offset: 4; indent-tabs-mode: t; -*- */
-/* Cairo - a vector graphics library with display and print output
- *
- * Copyright © 2022 Adrian Johnson
- *
- * This library is free software; you can redistribute it and/or
- * modify it either under the terms of the GNU Lesser General Public
- * License version 2.1 as published by the Free Software Foundation
- * (the "LGPL") or, at your option, under the terms of the Mozilla
- * Public License Version 1.1 (the "MPL"). If you do not alter this
- * notice, a recipient may use your version of this file under either
- * the MPL or the LGPL.
- *
- * You should have received a copy of the LGPL along with this library
- * in the file COPYING-LGPL-2.1; if not, write to the Free Software
- * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
- * You should have received a copy of the MPL along with this library
- * in the file COPYING-MPL-1.1
- *
- * The contents of this file are subject to the Mozilla Public License
- * Version 1.1 (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.mozilla.org/MPL/
- *
- * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY
- * OF ANY KIND, either express or implied. See the LGPL or the MPL for
- * the specific language governing rights and limitations.
- *
- * The Original Code is the cairo graphics library.
- *
- * The Initial Developer of the Original Code is Adrian Johnson
- *
- * Contributor(s):
- *	Adrian Johnson <ajohnson@redneon.com>
- */
-
-
-/* gtkdoc won't scan .cpp files so we wrap the public API in cairo-dwrite-font.cpp
- * with this .c wrapper containing the gtkdocs for cairo-dwrite-font.cpp.
- */
-
-#include "cairoint.h"
-#include "cairo-win32-private.h"
-
-/**
- * SECTION:cairo-dwrite-fonts
- * @Title: DWrite Fonts
- * @Short_Description: Font support for Microsoft DirectWrite
- * @See_Also: #cairo_font_face_t
- *
- * The Microsoft DirectWrite font backend is primarily used to render text on
- * Microsoft Windows systems.
- **/
-
-/**
- * CAIRO_HAS_DWRITE_FONT:
- *
- * Defined if the Microsoft DWrite font backend is available.
- * This macro can be used to conditionally compile backend-specific code.
- *
- * Since: 1.18
- **/
-
-/**
- * cairo_dwrite_font_face_create_for_dwrite_fontface:
- * @dwrite_font_face: A pointer to an #IDWriteFontFace specifying the
- * DWrite font to use.
- *
- * Creates a new font for the DWrite font backend based on a
- * DWrite font face. This font can then be used with
- * cairo_set_font_face() or cairo_scaled_font_create().
- *
- * Here is an example of how this function might be used:
- * <informalexample><programlisting><![CDATA[
- * #include <cairo-win32.h>
- * #include <dwrite.h>
- *
- * IDWriteFactory* dWriteFactory = NULL;
- * HRESULT hr = DWriteCreateFactory(
- *     DWRITE_FACTORY_TYPE_SHARED,
- *     __uuidof(IDWriteFactory),
- *    reinterpret_cast<IUnknown**>(&dWriteFactory));
- *
- * IDWriteFontCollection *systemCollection;
- * hr = dWriteFactory->GetSystemFontCollection(&systemCollection);
- *
- * UINT32 idx;
- * BOOL found;
- * systemCollection->FindFamilyName(L"Segoe UI Emoji", &idx, &found);
- *
- * IDWriteFontFamily *family;
- * systemCollection->GetFontFamily(idx, &family);
- *
- * IDWriteFont *dwritefont;
- * DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
- * DWRITE_FONT_STYLE style = DWRITE_FONT_STYLE_NORMAL;
- * hr = family->GetFirstMatchingFont(weight, DWRITE_FONT_STRETCH_NORMAL, style, &dwritefont);
- *
- * IDWriteFontFace *dwriteface;
- * hr = dwritefont->CreateFontFace(&dwriteface);
- *
- * cairo_font_face_t *face;
- * face = cairo_dwrite_font_face_create_for_dwrite_fontface(dwriteface);
- * cairo_set_font_face(cr, face);
- * cairo_set_font_size(cr, 70);
- * cairo_move_to(cr, 100, 100);
- * cairo_show_text(cr, "😃");
- * ]]></programlisting></informalexample>
- *
- * Note: When printing a DWrite font to a
- * #CAIRO_SURFACE_TYPE_WIN32_PRINTING surface, the printing surface
- * will substitute each DWrite font with a Win32 font created from the same
- * underlying font file. If the matching font file can not be found,
- * the #CAIRO_SURFACE_TYPE_WIN32_PRINTING surface will convert each
- * glyph to a filled path. If a DWrite font was not created from a system
- * font, it is recommended that the font used to create the DWrite
- * font be made available to GDI to avoid the undesirable fallback
- * to emitting paths. This can be achieved using the GDI font loading functions
- * such as AddFontMemResourceEx().
- *
- * Return value: a newly created #cairo_font_face_t. Free with
- *  cairo_font_face_destroy() when you are done using it.
- *
- * Since: 1.18
- **/
-cairo_font_face_t*
-cairo_dwrite_font_face_create_for_dwrite_fontface (void *dwrite_font_face)
-{
-    return cairo_dwrite_font_face_create_for_dwrite_fontface_internal (dwrite_font_face);
-}
diff --git a/src/win32/cairo-dwrite-font.cpp b/src/win32/cairo-dwrite-font.cpp
index f0657d636..fd866d4f0 100644
--- a/src/win32/cairo-dwrite-font.cpp
+++ b/src/win32/cairo-dwrite-font.cpp
@@ -49,6 +49,25 @@
 
 #include <wincodec.h>
 
+/**
+ * SECTION:cairo-dwrite-fonts
+ * @Title: DWrite Fonts
+ * @Short_Description: Font support for Microsoft DirectWrite
+ * @See_Also: #cairo_font_face_t
+ *
+ * The Microsoft DirectWrite font backend is primarily used to render text on
+ * Microsoft Windows systems.
+ **/
+
+/**
+ * CAIRO_HAS_DWRITE_FONT:
+ *
+ * Defined if the Microsoft DWrite font backend is available.
+ * This macro can be used to conditionally compile backend-specific code.
+ *
+ * Since: 1.18
+ **/
+
 typedef HRESULT (WINAPI*D2D1CreateFactoryFunc)(
     D2D1_FACTORY_TYPE factoryType,
     REFIID iid,
@@ -1322,8 +1341,70 @@ _cairo_dwrite_has_color_glyphs(void *scaled_font)
     return ((cairo_dwrite_font_face_t *)dwritesf->base.font_face)->have_color;
 }
 
+/**
+ * cairo_dwrite_font_face_create_for_dwrite_fontface:
+ * @dwrite_font_face: A pointer to an #IDWriteFontFace specifying the
+ * DWrite font to use.
+ *
+ * Creates a new font for the DWrite font backend based on a
+ * DWrite font face. This font can then be used with
+ * cairo_set_font_face() or cairo_scaled_font_create().
+ *
+ * Here is an example of how this function might be used:
+ * <informalexample><programlisting><![CDATA[
+ * #include <cairo-win32.h>
+ * #include <dwrite.h>
+ *
+ * IDWriteFactory* dWriteFactory = NULL;
+ * HRESULT hr = DWriteCreateFactory(
+ *     DWRITE_FACTORY_TYPE_SHARED,
+ *     __uuidof(IDWriteFactory),
+ *    reinterpret_cast<IUnknown**>(&dWriteFactory));
+ *
+ * IDWriteFontCollection *systemCollection;
+ * hr = dWriteFactory->GetSystemFontCollection(&systemCollection);
+ *
+ * UINT32 idx;
+ * BOOL found;
+ * systemCollection->FindFamilyName(L"Segoe UI Emoji", &idx, &found);
+ *
+ * IDWriteFontFamily *family;
+ * systemCollection->GetFontFamily(idx, &family);
+ *
+ * IDWriteFont *dwritefont;
+ * DWRITE_FONT_WEIGHT weight = DWRITE_FONT_WEIGHT_NORMAL;
+ * DWRITE_FONT_STYLE style = DWRITE_FONT_STYLE_NORMAL;
+ * hr = family->GetFirstMatchingFont(weight, DWRITE_FONT_STRETCH_NORMAL, style, &dwritefont);
+ *
+ * IDWriteFontFace *dwriteface;
+ * hr = dwritefont->CreateFontFace(&dwriteface);
+ *
+ * cairo_font_face_t *face;
+ * face = cairo_dwrite_font_face_create_for_dwrite_fontface(dwriteface);
+ * cairo_set_font_face(cr, face);
+ * cairo_set_font_size(cr, 70);
+ * cairo_move_to(cr, 100, 100);
+ * cairo_show_text(cr, "😃");
+ * ]]></programlisting></informalexample>
+ *
+ * Note: When printing a DWrite font to a
+ * #CAIRO_SURFACE_TYPE_WIN32_PRINTING surface, the printing surface
+ * will substitute each DWrite font with a Win32 font created from the same
+ * underlying font file. If the matching font file can not be found,
+ * the #CAIRO_SURFACE_TYPE_WIN32_PRINTING surface will convert each
+ * glyph to a filled path. If a DWrite font was not created from a system
+ * font, it is recommended that the font used to create the DWrite
+ * font be made available to GDI to avoid the undesirable fallback
+ * to emitting paths. This can be achieved using the GDI font loading functions
+ * such as AddFontMemResourceEx().
+ *
+ * Return value: a newly created #cairo_font_face_t. Free with
+ *  cairo_font_face_destroy() when you are done using it.
+ *
+ * Since: 1.18
+ **/
 cairo_font_face_t*
-cairo_dwrite_font_face_create_for_dwrite_fontface_internal(void* dwrite_font_face)
+cairo_dwrite_font_face_create_for_dwrite_fontface(void* dwrite_font_face)
 {
     IDWriteFontFace *dwriteface = static_cast<IDWriteFontFace*>(dwrite_font_face);
     // Must do malloc and not C++ new, since Cairo frees this.
diff --git a/src/win32/cairo-win32-private.h b/src/win32/cairo-win32-private.h
index d457b7805..486b12811 100644
--- a/src/win32/cairo-win32-private.h
+++ b/src/win32/cairo-win32-private.h
@@ -271,9 +271,6 @@ cairo_int_status_t
 _cairo_dwrite_scaled_font_create_win32_scaled_font (cairo_scaled_font_t *scaled_font,
                                                     cairo_scaled_font_t **new_font);
 
-cairo_font_face_t*
-cairo_dwrite_font_face_create_for_dwrite_fontface_internal(void* dwrite_font_face);
-
 #endif /* CAIRO_HAS_DWRITE_FONT */
 
 CAIRO_END_DECLS