tweak comments

git-svn-id: https://svn.r-project.org/R/trunk@87272 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: smeyer

src/library/base/man/Deprecated.Rd

@@ -27,17 +27,17 @@
   }
   \item{msg}{
     character string: A message to be printed, if missing a default
-    message is used.}
+    message is used.
+  }
   \item{old}{character string specifying the function (default) or usage
     which is being deprecated.}
 }
 \details{
-  \code{.Deprecated("\var{new name}")} is called from deprecated
-  functions.  The original help page for these functions is often
-  available at \code{help("\var{old}-deprecated")} (note the quotes).
-  % FIXME: the above is not true any more; the old \alias is usually kept as-is.
-  Deprecated functions should be listed in \code{help("\var{pkg}-deprecated")}
+  \code{.Deprecated("\var{new name}")} is called from deprecated functions.
+  These should be listed in \code{help("\var{pkg}-deprecated")}
   for an appropriate \var{pkg}, including \pkg{base}.
+  The original help page for a deprecated function is sometimes
+  available at \code{help("\var{old}-deprecated")} (note the quotes).
 
   \code{.Deprecated} signals a warning of class \code{"deprecatedWarning"}
   with fields \code{old}, \code{new}, and \code{package}.

src/library/tools/R/QC.R

@@ -1526,13 +1526,10 @@ function(package, dir, lib.loc = NULL, chkInternal = NULL)
         }
 
         ## Also test whether the objects we found from the \usage all
-        ## have aliases, provided that there is no alias which ends in
-        ## '-deprecated' (see e.g. base-deprecated.Rd).
-        ## <FIXME>
-        ## Why are we making the '-deprecated' exception?
-        ## Surely there should be aliases for such functions, and the
-        ## deprecated-Rd files in the base packages even say
-        ##   %------ PLEASE: put \alias{.} here for EACH !
+        ## have aliases, provided no alias ends in '-deprecated'.
+        ## This exception allows packages to keep the original help page of a
+        ## deprecated function at help("<fun>-deprecated") (see ?deprecated)
+        ## and alias <fun> to help("<pkg>-deprecated").
         functions_not_in_aliases <-
             if(!any(endsWith(aliases, "-deprecated"))) {
                 ## Argh.  There are good reasons for keeping \S4method{}{}
@@ -1549,7 +1546,6 @@ function(package, dir, lib.loc = NULL, chkInternal = NULL)
                 setdiff(functions, aliases)
             }
             else character()
-        ## </FIXME>
 
         if((length(arg_names_in_usage_missing_in_arg_list))
            || anyDuplicated(arg_names_in_arg_list)