refactor: improve code comments

Author: leeewee

src/bin/cargo-pta.rs

@@ -3,6 +3,13 @@
 // This source code is licensed under the GNU license found in the
 // LICENSE file in the root directory of this source tree.
 
+//! This provides an implementation for the "cargo pta" subcommand.
+//! 
+//! The subcommand is the same as "cargo check" but with three differences:
+//! 1) It implicitly adds the options "-Z always_encode_mir" to the rustc invocation.
+//! 2) It calls `pta` rather than `rustc` for all the targets of the current package.
+//! 3) It runs `cargo test --no-run` for test targets.
+
 use cargo_metadata::Package;
 use log::info;
 use rustc_tools_util::VersionInfo;
@@ -15,11 +22,15 @@ use std::process::{Command, Stdio};
 
 use rupta::util;
 
+/// The help message for `cargo-pta`
 const CARGO_PTA_HELP: &str = r#"Pointer analysis tool for Rust programs
 Usage:
     cargo pta
 "#;
 
+/// Set the environment variable `PTA_BUILD_STD` to enable the building of std library when running pta.
+const PTA_BUILD_STD: &str = "PTA_BUILD_STD";
+
 pub fn main() {
     if std::env::args().take_while(|a| a != "--").any(|a| a == "--help" || a == "-h") {
         println!("{}", CARGO_PTA_HELP);
@@ -126,17 +137,12 @@ fn call_cargo_on_target(target: &String, kind: &str) {
         if arg == "--" {
             break;
         }
-        if arg == "--no-std-build" {
-            continue;
-        }
         cmd.arg(arg);
     }
 
     // Enable Cargo to compile the standard library from source code as part of a crate graph compilation.
-    if !has_arg_flag("-Zbuild-std") && !has_arg_flag("build-std") {
-        if !has_arg_flag("--no-std-build") {
-            cmd.arg("-Zbuild-std");
-        }
+    if env::var(PTA_BUILD_STD).is_ok() {
+        cmd.arg("-Zbuild-std");
 
         if !has_arg_flag("--target") {
             let toolchain_target = toolchain_target().expect("could not get toolchain target");
@@ -244,15 +250,15 @@ fn call_rustc() {
     }
 }
 
-// Determines whether a flag `name` is present before `--`.
-// For example, has_arg_flag("-v")
+/// Determines whether a flag `name` is present before `--`.
+/// For example, has_arg_flag("-v")
 fn has_arg_flag(name: &str) -> bool {
     let mut args = std::env::args().take_while(|val| val != "--");
     args.any(|val| val == name)
 }
 
-// Gets the value of a `name`.
-// `--name value` or `--name=value`
+/// Gets the value of `name`.
+/// `--name value` or `--name=value`
 fn get_arg_flag_value(name: &str) -> Option<String> {
     let mut args = std::env::args().take_while(|val| val != "--");
     loop {
@@ -274,7 +280,7 @@ fn get_arg_flag_value(name: &str) -> Option<String> {
     }
 }
 
-// Returns the target of the toolchain, e.g. "x86_64-unknown-linux-gnu".
+/// Returns the target of the toolchain, e.g. "x86_64-unknown-linux-gnu".
 fn toolchain_target() -> Option<String> {
     let sysroot = util::find_sysroot();
 

src/bin/pta.rs

@@ -3,6 +3,11 @@
 // This source code is licensed under the GNU license found in the
 // LICENSE file in the root directory of this source tree.
 
+//! The main routine of `rupta`.
+//! 
+//! Implemented as a stub that invokes the rust compiler with a call back to execute 
+//! pointer analysis during rust compilation.
+
 #![feature(rustc_private)]
 
 extern crate rustc_driver;

src/builder/call_graph_builder.rs

@@ -3,38 +3,51 @@
 // This source code is licensed under the GNU license found in the
 // LICENSE file in the root directory of this source tree.
 
+//! This module provides essential functions for resolving call targets.
+
 use rustc_hir::def_id::DefId;
 use rustc_middle::ty::{GenericArgsRef, TyCtxt, TyKind};
 
 use crate::util;
 
-/// Try to resolve the given FnDef, devirtualize the callee function if possible.
+/// Try to resolve the function with `def_id` and `gen_args`. 
+/// 
+/// If the function is not a trait method, (`def_id`, `gen_args`) is returned
+/// directly. Otherwise, the function is devirtualized to a specific implementation.
 pub fn resolve_fn_def<'tcx>(
     tcx: TyCtxt<'tcx>,
-    callee_def_id: DefId,
+    def_id: DefId,
     gen_args: GenericArgsRef<'tcx>,
 ) -> (DefId, GenericArgsRef<'tcx>) {
-    if tcx.is_mir_available(callee_def_id) && !util::is_trait_method(tcx, callee_def_id) {
-        (callee_def_id, gen_args)
-    } else if let Some((callee_def_id, callee_substs)) =
-        try_to_devirtualize(tcx, callee_def_id, gen_args)
+    if tcx.is_mir_available(def_id) && !util::is_trait_method(tcx, def_id) {
+        (def_id, gen_args)
+    } else if let Some((resolved_def_id, resolved_substs)) =
+        try_to_devirtualize(tcx, def_id, gen_args)
     {
-        (callee_def_id, callee_substs)
+        (resolved_def_id, resolved_substs)
     } else {
-        // if the mir is unavailable or the callee cannot be resolved, return the callee_def_id directly
-        (callee_def_id, gen_args)
+        // if the function cannot be resolved, 
+        // return the original (def_id, gen_args) pair directly.
+        (def_id, gen_args)
     }
 }
 
+/// Try to devirtualize a trait method with `def_id` and `gen_args`. 
+/// 
+/// Returns `None` if the given `def_id` does not correspond to a trait method or 
+/// we cannot resolve the trait method to a specific instance. For example, the 
+/// first gen_arg is a dynamic type.
 pub fn try_to_devirtualize<'tcx>(
     tcx: TyCtxt<'tcx>,
-    callee_def_id: DefId,
+    def_id: DefId,
     gen_args: GenericArgsRef<'tcx>,
 ) -> Option<(DefId, GenericArgsRef<'tcx>)> {
-    if !util::is_trait_method(tcx, callee_def_id) {
+    if !util::is_trait_method(tcx, def_id) {
         return None;
     }
 
+    // A trait method cannot be devirtualized when the first gen_arg corresponds
+    // to a dynamic type.
     let arg0_ty = gen_args
         .types()
         .next()
@@ -45,20 +58,20 @@ pub fn try_to_devirtualize<'tcx>(
 
     let param_env = rustc_middle::ty::ParamEnv::reveal_all();
     let abi = tcx
-        .type_of(callee_def_id)
+        .type_of(def_id)
         .skip_binder()
         .fn_sig(tcx)
         .abi();    
     let resolved_instance = if abi == rustc_target::spec::abi::Abi::Rust {
         // Instance::resolve panics if try_normalize_erasing_regions returns an error.
-        // It is hard to figure out exactly when this will be the case.
+        // It is difficult to determine exactly when this error will occur.
         if tcx.try_normalize_erasing_regions(param_env, gen_args).is_err() {
             None
         } else {
             Some(rustc_middle::ty::Instance::resolve(
                 tcx,
                 param_env,
-                callee_def_id,
+                def_id,
                 gen_args,
             ))
         }
@@ -67,10 +80,6 @@ pub fn try_to_devirtualize<'tcx>(
     };
     if let Some(Ok(Some(instance))) = resolved_instance {
         let resolved_def_id = instance.def.def_id();
-        let has_mir = tcx.is_mir_available(resolved_def_id);
-        if !has_mir {
-            return None;
-        }
         return Some((resolved_def_id, instance.args));
     }
     None