Add comments ensuring that generics are cleaned before args

Otherwise, rustdoc panics with messages like this:

   thread 'rustc' panicked at 'assertion failed: cx.impl_trait_bounds.is_empty()',
   src/librustdoc/clean/utils.rs:462:5

This ordering requirement is unrelated to the `clean_fn_decl_with_args`
refactoring, but the requirement was uncovered as part of that change.

I'm not sure if *all* of these places have the requirement, but I added
comments to them just in case.

2 files changed, 5 insertions, 0 deletions

diff --git a/src/librustdoc/clean/inline.rs b/src/librustdoc/clean/inline.rs
index d670288270a..1324080b87e 100644
--- a/src/librustdoc/clean/inline.rs
+++ b/src/librustdoc/clean/inline.rs
@@ -229,6 +229,7 @@ fn build_external_function(cx: &mut DocContext<'_>, did: DefId) -> clean::Functi
     let asyncness = cx.tcx.asyncness(did);
     let predicates = cx.tcx.predicates_of(did);
     let (generics, decl) = clean::enter_impl_trait(cx, |cx| {
+        // NOTE: generics need to be cleaned before the decl!
         ((cx.tcx.generics_of(did), predicates).clean(cx), (did, sig).clean(cx))
     });
     clean::Function {
diff --git a/src/librustdoc/clean/mod.rs b/src/librustdoc/clean/mod.rs
index 4e1fd4f1136..d7eecdc598c 100644
--- a/src/librustdoc/clean/mod.rs
+++ b/src/librustdoc/clean/mod.rs
@@ -765,6 +765,7 @@ fn clean_fn_or_proc_macro(
 impl<'a> Clean<Function> for (&'a hir::FnSig<'a>, &'a hir::Generics<'a>, hir::BodyId) {
     fn clean(&self, cx: &mut DocContext<'_>) -> Function {
         let (generics, decl) = enter_impl_trait(cx, |cx| {
+            // NOTE: generics must be cleaned before args
             let generics = self.1.clean(cx);
             let args = (self.0.decl.inputs, self.2).clean(cx);
             let decl = clean_fn_decl_with_args(cx, self.0.decl, args);
@@ -896,6 +897,7 @@ impl Clean<Item> for hir::TraitItem<'_> {
                 }
                 hir::TraitItemKind::Fn(ref sig, hir::TraitFn::Required(names)) => {
                     let (generics, decl) = enter_impl_trait(cx, |cx| {
+                        // NOTE: generics must be cleaned before args
                         let generics = self.generics.clean(cx);
                         let args = (sig.decl.inputs, names).clean(cx);
                         let decl = clean_fn_decl_with_args(cx, sig.decl, args);
@@ -1732,6 +1734,7 @@ impl Clean<PathSegment> for hir::PathSegment<'_> {
 impl Clean<BareFunctionDecl> for hir::BareFnTy<'_> {
     fn clean(&self, cx: &mut DocContext<'_>) -> BareFunctionDecl {
         let (generic_params, decl) = enter_impl_trait(cx, |cx| {
+            // NOTE: generics must be cleaned before args
             let generic_params = self.generic_params.iter().map(|x| x.clean(cx)).collect();
             let args = (self.decl.inputs, self.param_names).clean(cx);
             let decl = clean_fn_decl_with_args(cx, self.decl, args);
@@ -2032,6 +2035,7 @@ impl Clean<Item> for (&hir::ForeignItem<'_>, Option<Symbol>) {
                 hir::ForeignItemKind::Fn(decl, names, ref generics) => {
                     let abi = cx.tcx.hir().get_foreign_abi(item.hir_id());
                     let (generics, decl) = enter_impl_trait(cx, |cx| {
+                        // NOTE: generics must be cleaned before args
                         let generics = generics.clean(cx);
                         let args = (decl.inputs, names).clean(cx);
                         let decl = clean_fn_decl_with_args(cx, decl, args);