From 9118037b3be0f928749ce56050de506705c9348a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Wed, 22 Aug 2018 21:49:53 +0200
Subject: [PATCH] doc: mention EM_ASM() and dollar warnings.

---
 doc/platforms-html5.dox          | 15 ++++++++++++
 doc/snippets/CMakeLists.txt      |  7 +++++-
 doc/snippets/platforms-html5.cpp | 41 ++++++++++++++++++++++++++++++++
 3 files changed, 62 insertions(+), 1 deletion(-)
 create mode 100644 doc/snippets/platforms-html5.cpp

diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox
index 33d89c8fb..a772fb5ba 100644
--- a/doc/platforms-html5.dox
+++ b/doc/platforms-html5.dox
@@ -554,6 +554,21 @@ the mapping [can be added programmatically](https://docs.python.org/3/library/ht
 http.server.SimpleHTTPRequestHandler.extensions_map['.wasm'] = 'application/wasm'
 @endcode
 
+@subsection platforms-html5-troubleshooting-emasm Warnings about $ characters when using EM_ASM
+
+The [EM_ASM()](https://kripken.github.io/emscripten-site/docs/porting/connecting_cpp_and_javascript/Interacting-with-code.html#interacting-with-code-call-javascript-from-native)
+family of macros is using `$0`, `$1`, ... to refer to macro arguments from
+JavaScript code. Using them in C++ sources triggers a warning from Clang:
+
+@code{.shell-session}
+warning: '$' in identifier
+@endcode
+
+Solution is to disable the warning for the offending lines, here for example
+when modifying a title element contents through DOM:
+
+@snippet platforms-html5.cpp emasm-dollar
+
 */
 
 }
diff --git a/doc/snippets/CMakeLists.txt b/doc/snippets/CMakeLists.txt
index 7b5cfbeba..661b4ac75 100644
--- a/doc/snippets/CMakeLists.txt
+++ b/doc/snippets/CMakeLists.txt
@@ -38,12 +38,17 @@ if(CORRADE_TARGET_EMSCRIPTEN AND NOT TARGET_GLES2)
     set(CMAKE_EXE_LINKER_FLAGS "${CMAKE_EXE_LINKER_FLAGS} -s USE_WEBGL2=1")
 endif()
 
-add_library(snippets-Magnum STATIC
+set(snippets_Magnum_SRCS
     Magnum.cpp
     MagnumAnimation.cpp
     MagnumAnimation-custom.cpp
     MagnumMath.cpp
     MagnumMathAlgorithms.cpp)
+if(CORRADE_TARGET_EMSCRIPTEN)
+    list(APPEND snippets_Magnum_SRCS platforms-html5.cpp)
+endif()
+
+add_library(snippets-Magnum STATIC ${snippets_Magnum_SRCS})
 target_link_libraries(snippets-Magnum PRIVATE Magnum)
 set_target_properties(snippets-Magnum PROPERTIES FOLDER "Magnum/doc/snippets")
 
diff --git a/doc/snippets/platforms-html5.cpp b/doc/snippets/platforms-html5.cpp
new file mode 100644
index 000000000..edb310db2
--- /dev/null
+++ b/doc/snippets/platforms-html5.cpp
@@ -0,0 +1,41 @@
+/*
+    This file is part of Magnum.
+
+    Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018
+              Vladimír Vondruš <mosra@centrum.cz>
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included
+    in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+*/
+
+#include <string>
+#include <emscripten/emscripten.h>
+
+int main() {
+{
+/* [emasm-dollar] */
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wdollar-in-identifier-extension"
+std::string title;
+EM_ASM_({document.getElementById('title').innerHTML =
+    Pointer_stringify($0, $1)}, title.data(), title.size());
+#pragma GCC diagnostic pop
+/* [emasm-dollar] */
+}
+
+}