Docs: Update link_language docs to explain when it should be used

2 files changed, 14 insertions, 2 deletions

diff --git a/docs/markdown/Reference-manual.md b/docs/markdown/Reference-manual.md
index 963af9d..5c5f56a 100644
--- a/docs/markdown/Reference-manual.md
+++ b/docs/markdown/Reference-manual.md
@@ -600,8 +600,12 @@ be passed to [shared and static libraries](#library).
   depends on such as a symbol visibility map. The purpose is to
   automatically trigger a re-link (but not a re-compile) of the target
   when this file changes.
-- `link_language` since 0.51.0 makes the linker for this target
-  be for the specified language. This is helpful for multi-language targets.
+- `link_language` since 0.51.0 (broken until 0.55.0) makes the linker for this
+  target be for the specified language. It is generally unnecessary to set
+  this, as meson will detect the right linker to use in most cases. There are
+  only two cases where this is needed. One, your main function in an
+  executable is not in the language meson picked, or second you want to force
+  a library to use only one ABI.
 - `link_whole` links all contents of the given static libraries
   whether they are used by not, equivalent to the
   `-Wl,--whole-archive` argument flag of GCC, available since 0.40.0.
diff --git a/docs/markdown/snippets/link_language_all_targets.md b/docs/markdown/snippets/link_language_all_targets.md
new file mode 100644
index 0000000..9019d50
--- /dev/null
+++ b/docs/markdown/snippets/link_language_all_targets.md
@@ -0,0 +1,8 @@
+## link_language argument added to all targets
+
+Previously the `link_language` argument was only supposed to be allowed in
+executables, because the linker used needs to be the linker for the language
+that implements the main function. Unfortunately it didn't work in that case,
+and, even worse, if it had been implemented properly it would have worked for
+*all* targets. In 0.55.0 this restriction has been removed, and the bug fixed.
+It now is valid for `executable` and all derivative of `library`.