Document almost all modules

Fixes #1082

Author: bjorn3

src/abi/comments.rs

@@ -1,3 +1,6 @@
+//! Annotate the clif ir with comments describing how arguments are passed into the current function
+//! and where all locals are stored.
+
 use std::borrow::Cow;
 
 use rustc_middle::mir;

src/abi/mod.rs

@@ -1,3 +1,5 @@
+//! Handling of everything related to the calling convention. Also fills `fx.local_map`.
+
 #[cfg(debug_assertions)]
 mod comments;
 mod pass_mode;
@@ -325,6 +327,7 @@ impl<'tcx, B: Backend + 'static> FunctionCx<'_, 'tcx, B> {
     }
 }
 
+/// Make a [`CPlace`] capable of holding value of the specified type.
 fn make_local_place<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     local: Local,

src/abi/pass_mode.rs

@@ -1,3 +1,5 @@
+//! Argument passing
+
 use crate::prelude::*;
 
 pub(super) use EmptySinglePair::*;
@@ -118,6 +120,7 @@ pub(super) fn get_pass_mode<'tcx>(tcx: TyCtxt<'tcx>, layout: TyAndLayout<'tcx>)
     }
 }
 
+/// Get a set of values to be passed as function arguments.
 pub(super) fn adjust_arg_for_abi<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     arg: CValue<'tcx>,
@@ -136,6 +139,8 @@ pub(super) fn adjust_arg_for_abi<'tcx>(
     }
 }
 
+/// Create a [`CValue`] containing the value of a function parameter adding clif function parameters
+/// as necessary.
 pub(super) fn cvalue_for_param<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     start_block: Block,

src/abi/returning.rs

@@ -1,10 +1,13 @@
+//! Return value handling
+
 use crate::abi::pass_mode::*;
 use crate::prelude::*;
 
 fn return_layout<'a, 'tcx>(fx: &mut FunctionCx<'a, 'tcx, impl Backend>) -> TyAndLayout<'tcx> {
     fx.layout_of(fx.monomorphize(&fx.mir.local_decls[RETURN_PLACE].ty))
 }
 
+/// Can the given type be returned into an ssa var or does it need to be returned on the stack.
 pub(crate) fn can_return_to_ssa_var<'tcx>(
     tcx: TyCtxt<'tcx>,
     dest_layout: TyAndLayout<'tcx>,
@@ -16,6 +19,8 @@ pub(crate) fn can_return_to_ssa_var<'tcx>(
     }
 }
 
+/// Return a place where the return value of the current function can be written to. If necessary
+/// this adds an extra parameter pointing to where the return value needs to be stored.
 pub(super) fn codegen_return_param<'tcx>(
     fx: &mut FunctionCx<'_, 'tcx, impl Backend>,
     ssa_analyzed: &rustc_index::vec::IndexVec<Local, crate::analyze::SsaKind>,
@@ -59,6 +64,8 @@ pub(super) fn codegen_return_param<'tcx>(
     ret_place
 }
 
+/// Invokes the closure with if necessary a value representing the return pointer. When the closure
+/// returns the call return value(s) if any are written to the correct place.
 pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>(
     fx: &mut FunctionCx<'_, 'tcx, B>,
     fn_sig: FnSig<'tcx>,
@@ -102,6 +109,7 @@ pub(super) fn codegen_with_call_return_arg<'tcx, B: Backend, T>(
     (call_inst, meta)
 }
 
+/// Codegen a return instruction with the right return value(s) if any.
 pub(crate) fn codegen_return(fx: &mut FunctionCx<'_, '_, impl Backend>) {
     match get_pass_mode(fx.tcx, return_layout(fx)) {
         PassMode::NoPass | PassMode::ByRef { size: Some(_) } => {

src/allocator.rs

@@ -1,12 +1,5 @@
-// Copyright 2017 The Rust Project Developers. See the COPYRIGHT
-// file at the top-level directory of this distribution and at
-// http://rust-lang.org/COPYRIGHT.
-//
-// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
-// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
-// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
-// option. This file may not be copied, modified, or distributed
-// except according to those terms.
+//! Allocator shim
+// Adapted from rustc
 
 use crate::prelude::*;
 

src/analyze.rs

@@ -1,3 +1,5 @@
+//! SSA analysis
+
 use crate::prelude::*;
 
 use rustc_index::vec::IndexVec;

src/archive.rs

@@ -1,3 +1,5 @@
+//! Creation of ar archives like for the lib and staticlib crate type
+
 use std::collections::BTreeMap;
 use std::fs::File;
 use std::path::{Path, PathBuf};

src/backend.rs

@@ -1,3 +1,5 @@
+//! Abstraction around the object writing crate
+
 use std::convert::{TryFrom, TryInto};
 
 use rustc_data_structures::fx::FxHashMap;

src/base.rs

@@ -1,3 +1,5 @@
+//! Codegen of a single function
+
 use rustc_index::vec::IndexVec;
 use rustc_middle::ty::adjustment::PointerCast;
 

src/cast.rs

@@ -1,3 +1,5 @@
+//! Various number casting functions
+
 use crate::prelude::*;
 
 pub(crate) fn clif_intcast(