Skip to content

Commit 9987aec

Browse files
rizsottorizsotto
committed
rust: module documentation updates
1 parent 9a347a3 commit 9987aec

File tree

5 files changed

+121
-68
lines changed

5 files changed

+121
-68
lines changed

‎rust/bear/src/config.rs‎

Lines changed: 75 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,80 @@
11
// SPDX-License-Identifier: GPL-3.0-or-later
22

3+
//! This module defines the configuration of the application.
4+
//!
5+
//! The configuration is either loaded from a file or used with the default
6+
//! values, which are defined in the code. The configuration exposes the main
7+
//! logical steps that the application will follow.
8+
//!
9+
//! The configuration file syntax is based on the YAML format.
10+
//! The default configuration file name is `bear.yml`.
11+
//!
12+
//! The configuration file location is searched in the following order:
13+
//! - The current working directory.
14+
//! - The local configuration directory of the user.
15+
//! - The configuration directory of the user.
16+
//! - The local configuration directory of the application.
17+
//! - The configuration directory of the application.
18+
//!
19+
//! The configuration file content is validated against the schema version,
20+
//! syntax and semantic constraints. If the configuration file is invalid,
21+
//! the application will exit with an error message explaining the issue.
22+
//!
23+
//! ```yaml
24+
//! schema: 4.0
25+
//!
26+
//! intercept:
27+
//! mode: wrapper
28+
//! directory: /tmp
29+
//! executables:
30+
//! - /usr/bin/cc
31+
//! - /usr/bin/c++
32+
//! output:
33+
//! specification: clang
34+
//! compilers:
35+
//! - path: /usr/local/bin/cc
36+
//! ignore: always
37+
//! - path: /usr/local/bin/c++
38+
//! ignore: conditional
39+
//! arguments:
40+
//! match:
41+
//! - -###
42+
//! - path: /usr/local/bin/clang
43+
//! ignore: never
44+
//! arguments:
45+
//! add:
46+
//! - -DDEBUG
47+
//! remove:
48+
//! - -Wall
49+
//! - path: /usr/local/bin/clang++
50+
//! arguments:
51+
//! remove:
52+
//! - -Wall
53+
//! filter:
54+
//! source:
55+
//! include_only_existing_files: true
56+
//! paths_to_include:
57+
//! - sources
58+
//! paths_to_exclude:
59+
//! - tests
60+
//! duplicates:
61+
//! by_fields:
62+
//! - file
63+
//! - directory
64+
//! format:
65+
//! command_as_array: true
66+
//! drop_output_field: false
67+
//! ```
68+
//!
69+
//! ```yaml
70+
//! schema: 4.0
71+
//!
72+
//! intercept:
73+
//! mode: preload
74+
//! output:
75+
//! specification: bear
76+
//! ```
77+
378
use std::collections::HashSet;
479
use std::fs::OpenOptions;
580
use std::path::{Path, PathBuf};
@@ -14,61 +89,6 @@ const PRELOAD_LIBRARY_PATH: &str = env!("PRELOAD_LIBRARY_PATH");
1489
const WRAPPER_EXECUTABLE_PATH: &str = env!("WRAPPER_EXECUTABLE_PATH");
1590

1691
/// Represents the application configuration.
17-
///
18-
/// ```yaml
19-
/// schema: 4.0
20-
///
21-
/// intercept:
22-
/// mode: wrapper
23-
/// directory: /tmp
24-
/// executables:
25-
/// - /usr/bin/cc
26-
/// - /usr/bin/c++
27-
/// output:
28-
/// specification: clang
29-
/// compilers:
30-
/// - path: /usr/local/bin/cc
31-
/// ignore: always
32-
/// - path: /usr/local/bin/c++
33-
/// ignore: conditional
34-
/// arguments:
35-
/// match:
36-
/// - -###
37-
/// - path: /usr/local/bin/clang
38-
/// ignore: never
39-
/// arguments:
40-
/// add:
41-
/// - -DDEBUG
42-
/// remove:
43-
/// - -Wall
44-
/// - path: /usr/local/bin/clang++
45-
/// arguments:
46-
/// remove:
47-
/// - -Wall
48-
/// filter:
49-
/// source:
50-
/// include_only_existing_files: true
51-
/// paths_to_include:
52-
/// - sources
53-
/// paths_to_exclude:
54-
/// - tests
55-
/// duplicates:
56-
/// by_fields:
57-
/// - file
58-
/// - directory
59-
/// format:
60-
/// command_as_array: true
61-
/// drop_output_field: false
62-
/// ```
63-
///
64-
/// ```yaml
65-
/// schema: 4.0
66-
///
67-
/// intercept:
68-
/// mode: preload
69-
/// output:
70-
/// specification: bear
71-
/// ```
7292
#[derive(Debug, PartialEq, Deserialize, Serialize)]
7393
pub struct Main {
7494
#[serde(deserialize_with = "validate_schema_version")]

‎rust/bear/src/output/clang/mod.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
// SPDX-License-Identifier: GPL-3.0-or-later
2+
23
//! This crate provides support for reading and writing JSON compilation database files.
34
//!
45
//! A compilation database is a set of records which describe the compilation of the

‎rust/bear/src/recognition.rs‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,29 @@
11
// SPDX-License-Identifier: GPL-3.0-or-later
2+
3+
//! Responsible for recognizing the semantic meaning of the executed commands.
4+
//!
5+
//! The recognition logic is implemented in the `interpreters` module.
6+
//! Here we only handle the errors and logging them to the console.
7+
28
use super::{config, semantic};
39
use intercept::Execution;
410
use std::convert::TryFrom;
511

6-
/// Responsible for recognizing the semantic meaning of the executed commands.
7-
///
8-
/// The recognition logic is implemented in the `interpreters` module. Here we only handle
9-
/// the errors and logging them to the console.
1012
pub struct Recognition {
1113
interpreter: Box<dyn semantic::Interpreter>,
1214
}
1315

1416
impl TryFrom<&config::Main> for Recognition {
1517
type Error = anyhow::Error;
1618

19+
/// Creates an interpreter to recognize the compiler calls.
20+
///
21+
/// Using the configuration we can define which compilers to include and exclude.
22+
/// Also read the environment variables to detect the compiler to include (and
23+
/// make sure those are not excluded either).
24+
// TODO: Use the CC or CXX environment variables to detect the compiler to include.
25+
// Use the CC or CXX environment variables and make sure those are not excluded.
26+
// Make sure the environment variables are passed to the method.
1727
fn try_from(config: &config::Main) -> Result<Self, Self::Error> {
1828
let compilers_to_include = match &config.intercept {
1929
config::Intercept::Wrapper { executables, .. } => executables.clone(),
@@ -39,6 +49,8 @@ impl TryFrom<&config::Main> for Recognition {
3949
}
4050

4151
impl Recognition {
52+
/// Simple call the semantic module to recognize the execution.
53+
/// Forward only the compiler calls, and log each recognition result.
4254
pub fn apply(&self, execution: Execution) -> Option<semantic::Meaning> {
4355
match self.interpreter.recognize(&execution) {
4456
semantic::Recognition::Success(semantic::Meaning::Ignored) => {

‎rust/bear/src/semantic/mod.rs‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,15 @@
11
// SPDX-License-Identifier: GPL-3.0-or-later
22

3+
//! This module is defining the semantic of executed commands.
4+
//!
5+
//! The semantic identifies the intent of the execution. It not only
6+
//! recognizes the compiler calls, but also identifies the compiler
7+
//! passes that are executed.
8+
//!
9+
//! A compilation of a source file can be divided into multiple passes.
10+
//! We are interested in the compiler passes, because those are the
11+
//! ones that are relevant to build a JSON compilation database.
12+
313
pub mod interpreters;
414

515
use intercept::Execution;
@@ -29,17 +39,24 @@ pub enum CompilerPass {
2939
},
3040
}
3141

32-
/// This abstraction is representing a tool which semantic we are aware of.
42+
/// Responsible to recognize the semantic of an executed command.
43+
///
44+
/// The implementation can be responsible for a single compiler,
45+
/// a set of compilers, or a set of commands that are not compilers.
3346
///
34-
/// A single tool has a potential to recognize a command execution and
35-
/// identify the semantic of that command. This abstraction is also can
36-
/// represent a set of interpreters, and the recognition process can be
37-
/// distributed amongst the interpreters.
47+
/// The benefit to recognize a non-compiler command, is to not
48+
/// spend more time to try to recognize with other interpreters.
49+
/// Or classify the recognition as ignored to not be further processed
50+
/// later on.
3851
pub trait Interpreter: Send {
3952
fn recognize(&self, _: &Execution) -> Recognition<Meaning>;
4053
}
4154

4255
/// Represents a semantic recognition result.
56+
///
57+
/// The unknown recognition is used when the interpreter is not
58+
/// able to recognize the command. This can signal the search process
59+
/// to continue with the next interpreter.
4360
#[derive(Debug, PartialEq)]
4461
pub enum Recognition<T> {
4562
Success(T),

‎rust/bear/src/transformation.rs‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
// SPDX-License-Identifier: GPL-3.0-or-later
2+
3+
//! Responsible for transforming the compiler calls.
4+
//!
5+
//! It conditionally removes compiler calls based on compiler names or flags.
6+
//! It can also alter the compiler flags of the compiler calls. The actions
7+
//! are defined in the configuration this module is given.
8+
29
use super::{config, semantic};
310

4-
/// Responsible for transforming the semantic meaning of the compiler calls.
5-
///
6-
/// It conditionally removes compiler calls based on compiler names or flags.
7-
/// It can also add or remove flags from the compiler calls.
811
pub enum Transformation {
912
None,
1013
Config(Vec<config::Compiler>),

0 commit comments

Comments
 (0)