transpile: rename fn sort_top_decls to sort_top_decls_for_emitting and add docs

Author: kkysen

c2rust-transpile/src/c_ast/mod.rs

@@ -986,8 +986,10 @@ impl TypedAstContext {
         }
     }
 
-    pub fn sort_top_decls(&mut self) {
-        // Group and sort declarations by file and by position
+    /// Sort the top-level declarations by file and source location
+    /// so that we preserve the ordering of all declarations in each file.
+    /// This preserves the order when we emit the converted declarations.
+    pub fn sort_top_decls_for_emitting(&mut self) {
         let mut decls_top = mem::take(&mut self.c_decls_top);
         decls_top.sort_unstable_by(|a, b| {
             let a = self.index(*a);

c2rust-transpile/src/translator/mod.rs

@@ -738,9 +738,7 @@ pub fn translate(
             })
             .collect::<HashMap<_, _>>();
 
-        // Sort the top-level declarations by file and source location so that we
-        // preserve the ordering of all declarations in each file.
-        t.ast_context.sort_top_decls();
+        t.ast_context.sort_top_decls_for_emitting();
 
         for top_id in &t.ast_context.c_decls_top {
             let decl = t.ast_context.get_decl(top_id).unwrap();