From 96624699577c7497fda3592088f3928867dff381 Mon Sep 17 00:00:00 2001
From: Piotr Kaczorowski <piotr.kaczorowski@gmail.com>
Date: Mon, 4 Jan 2021 22:05:55 +0100
Subject: [PATCH] Return-type warning and pseudo variable __A__ documentation
 added.

---
 doc/cc65.sgml | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/doc/cc65.sgml b/doc/cc65.sgml
index e273ced9c..211aa21b3 100644
--- a/doc/cc65.sgml
+++ b/doc/cc65.sgml
@@ -549,6 +549,8 @@ Here is a description of all the command line options:
   <tag><tt/remap-zero/</tag>
         Warn about a <tt/<ref id="pragma-charmap" name="#pragma charmap()">/
         that changes a character's code number from/to 0x00.
+  <tag><tt/return-type/</tag>
+        Warn about no return statement in function returning non-void..
   <tag><tt/struct-param/</tag>
         Warn when passing structs by value.
   <tag><tt/unknown-pragma/</tag>
@@ -726,6 +728,29 @@ This cc65 version has some extensions to the ISO C standard.
         will give the high byte of any unsigned value.
         <p>
 
+<item>  There is pseudo variable named <tt/__A__/ that indicates accumulator register. 
+        It can be used to highlight the returned variable in non-void
+        function where result is hidden in the <tt/asm/ section.
+        every other variable. They are most useful together with short
+        sequences of assembler code. 
+
+    For example, in the function below
+
+        <tscreen><verb>
+        BYTE get_key_via_atarixl_romcall_device_k(void)      \
+            asm("LDA $E425");   \
+            asm("PHA");         \
+            asm("LDA $E424");   \
+            asm("PHA");         \
+            asm("RTA");         \
+            return __A__;
+        </verb></tscreen>
+
+        <tt/return __A__;/ will indicate that result is stored in the accumulator
+        and suppress warning that function has no return statement. Instead, you can
+        also use <tt/#pragma warn (return-type, off) ... pragma warn (return-type, on)/
+        <p>
+
 <item>  Inside a function, the identifier <tt/__func__/ gives the name of the
         current function as a string. Outside of functions, <tt/__func__/ is
         undefined.