From: Yannick Moy <moy@adacore.com>
Date: Mon, 6 Jul 2020 16:17:34 +0000 (+0200)
Subject: [Ada] Clarify current design of Errout wrt global variable usage
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=fa366a96d003a3868dd33dd6a3c36eda3240a659;p=gcc.git

[Ada] Clarify current design of Errout wrt global variable usage

gcc/ada/

	* errout.ads: Add comment regarding lack of preservation of
	Errout state across successive calls to the API.
---

diff --git a/gcc/ada/errout.ads b/gcc/ada/errout.ads
index 83a23cc63f0..53c7e2bd8fd 100644
--- a/gcc/ada/errout.ads
+++ b/gcc/ada/errout.ads
@@ -453,6 +453,15 @@ package Errout is
    --  Note that is mandatory that the caller ensure that global variables
    --  are set before the Error_Msg call, otherwise the result is undefined.
 
+   --  Also note that calls to Error_Msg and its variants destroy the value of
+   --  these global variables, as a way to support the inclusion of multiple
+   --  insertion characters of the same type. For example, support for
+   --  multiple characters % for a name in the message (up to 3) is
+   --  implemented by unconditionally shifting the value for Error_Msg_Nam_2
+   --  to Error_Msg_Nam_1 and from Error_Msg_Nam_3 to Error_Msg_Nam_2 after
+   --  dealing with insertion character %. The caller should ensure that all
+   --  global variables are restored if needed prior to calling Error_Msg.
+
    Error_Msg_Col : Column_Number renames Err_Vars.Error_Msg_Col;
    --  Column for @ insertion character in message