GP-4324 Improved Function Editor for Decompiler use to limit full com…

…mit and added checkbox to control full commit

Ghidra/Features/Base/src/main/help/help/topics/FunctionPlugin/Variables.htm

@@ -29,10 +29,16 @@ <H2>Function Signature</H2>
       <LI>Ordered list of named parameters and associated data types.</LI>
     </OL>
 
+    <BLOCKQUOTE>
+      <P><IMG src="help/shared/note.png" alt="Note:">
+      While certain changes may be made without commiting all return and parameter details, those
+      changes which are made that require a full commit will cause the  
+      <A href="#CommitDetails">Commit all return/parameter details</A> checkbox to be enabled.
+      The user may choose to alter this full commit by checking or unchecking the corresponding
+      checkbox.
+      </P>
+    </BLOCKQUOTE>
 
-
-
-
     <H2><A name="Function_Attributes"></A>Function Attributes</H2>
 
     <BLOCKQUOTE>
@@ -289,11 +295,9 @@ <H2><A name="Edit_Function">Edit Function</A></H2>
 
       <OL>
         <LI>Place the cursor on a function signature</LI>
-
         <LI>Right-mouse-click, and select <I>Edit Function</I>.</LI>
-
         <LI>Edit any attributes of the function using the dialog.</LI>
-
+		<LI>Consider <A href="#CommitDetails">committing all return/parameter details</A></LI>
         <LI>Press <I>OK</I> to save your changes.</LI>
       </OL>
 
@@ -396,6 +400,35 @@ <H3>Call Fixup</H3>
       the compiler specification (*.cspec file) associated with a program. This feature is
       typically used when the effects of calling a well-known function need to be simplified so
       that the caller can be more easily analyzed and/or understood.</P>
+
+      <H3><A name="CommitDetails">Commit all return/parameter details</A></H3>
+
+      <P>This checkbox controls whether a complete function update will be performed, including
+      datatype and optional custom-storage details, for the return and all parameters.  
+      This checkbox will enable itself when
+      specific changes are made which require a complete commit in order to preserve what is seen
+      in the editor.  Use of custom storage or altering return or parameter datatypes will require
+      a full commit in order to retain such changes.  It is important to note that a full Commit 
+      with storage and/or datatype changes will impose a <I>USER_DEFINED</I> <B>Signature Source</B>
+      which will lock-in parameter details within the Decompiler.  The <B>Signature Source</B>
+      Function Listing Field can be useful for monitoring this state.</P>
+
+      <BLOCKQUOTE>
+        <P><IMG alt="" src="images/warning.help.png">
+        If the signature has been autogenerated by the decompiler and changes have been made to 
+        things other than the signature, like calling convention or callfixup, that may affect the 
+        generated signature.  Consider changing the calling convention only to check if the 
+        decompiler would generate the same signature unless you are sure the generated signature 
+        is correct.</P>
+      </BLOCKQUOTE>
+
+      <P>Prior to clicking the dialog's <B>OK</B> button the user may uncheck this control to
+      prevent return/parameter changes from being committed.  Once datatype or custom-storage 
+      choices have been changed, any parameter name changes will also require a full commit to 
+      preserve such changes.  A full commit is not required if only parameter names have been
+      changed.  The exception to this is when the Function Editor is used within the Decompiler
+      and parameters have not previously be committed.</P>
+
     </BLOCKQUOTE>
 
     <H2><A name="Edit_Parameter_Storage"></A>Edit Parameter Storage Dialog</H2>