Merge branch 'dev'

Author: PicoJr

CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.1](https://crates.io/crates/rtw/1.2.1) Jun 07, 2020
+
+* Add warning: CLI usage stable but not `lib.rs` content.
+* Fix doc.rs build issue (restore `lib.rs`).
+
 ## [1.2.0](https://crates.io/crates/rtw/1.2.0) Jun 07, 2020
 
 * add `cancel` subcommand.

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "rtw"
-version = "1.2.0"
+version = "1.2.1"
 authors = ["PicoJr <picojr_dev@gmx.com>"]
 edition = "2018"
 repository = "https://github.com/PicoJr/rtw"

Cargo.toml

@@ -11,6 +11,8 @@
 
 Command-line interface (CLI) time tracker.
 
+CLI usage is stable, underlying API is **not stable**.
+
 This project is heavily inspired from [Timewarrior](https://github.com/GothenburgBitFactory/timewarrior).
 
 > For a stable feature-rich CLI time tracker, please use Timewarrior: https://timewarrior.net/.

README.md

@@ -1,3 +1,4 @@
+//! Clock impl using chrono.
 use crate::rtw_core::clock::{Clock, Time};
 use crate::rtw_core::datetimew::DateTimeW;
 use chrono::{Date, Datelike, Duration, Local};

src/chrono_clock.rs

@@ -1,3 +1,4 @@
+//! CLI parsing helpers and clap App.
 use clap::{App, Arg, ArgMatches, SubCommand};
 
 use crate::rtw_core::clock::{Clock, Time};

src/cli_helper.rs

@@ -1,3 +1,4 @@
+//! Store activities (current, finished) as Json files.
 use crate::rtw_core::activity::{Activity, OngoingActivity};
 use crate::rtw_core::storage::Storage;
 use crate::rtw_core::ActivityId;

src/json_storage.rs

@@ -0,0 +1,33 @@
+//! # RTW
+//!
+//! Command-line interface (CLI) time tracker.
+//!
+//! CLI usage is stable, underlying API is **not stable**.
+//!
+//! This project is heavily inspired from [Timewarrior](https://github.com/GothenburgBitFactory/timewarrior).
+//!
+//! For a stable feature-rich CLI time tracker, please use Timewarrior: <https://timewarrior.net/>.
+//!
+//! ## Design
+//!
+//! * Activities are stored inside a `Storage`.
+//! * An `ActivityService` provides the logic above a storage.
+//! * `rtw_cli::run` translates CLI args to actions (`RTWAction`).
+//! * `rtw_cli::run_action` performs actions `RTWAction` by calling the service.
+//!
+//! ## Tests
+//!
+//! RTW has both unit and integration tests.
+
+#[macro_use]
+extern crate clap;
+
+pub mod chrono_clock;
+pub mod cli_helper;
+pub mod json_storage;
+pub mod rtw_cli;
+pub mod rtw_config;
+pub mod rtw_core;
+pub mod service;
+pub mod time_tools;
+mod timeline;

src/lib.rs

@@ -1,23 +1,11 @@
-#[macro_use]
-extern crate clap;
-
-use crate::chrono_clock::ChronoClock;
-use crate::json_storage::JsonStorage;
-use crate::rtw_cli::{run, run_action};
-use crate::service::Service;
+use rtw::chrono_clock::ChronoClock;
+use rtw::json_storage::JsonStorage;
+use rtw::rtw_cli::{run, run_action};
+use rtw::service::Service;
+use rtw::{cli_helper, rtw_config};
 use std::path::PathBuf;
 use std::str::FromStr;
 
-mod chrono_clock;
-mod cli_helper;
-mod json_storage;
-mod rtw_cli;
-mod rtw_config;
-mod rtw_core;
-mod service;
-mod time_tools;
-mod timeline;
-
 fn main() -> anyhow::Result<()> {
     let cli_helper = cli_helper::ActivityCli {};
     let config = rtw_config::load_config()?;
@@ -36,5 +24,6 @@ fn main() -> anyhow::Result<()> {
     ));
 
     let action = run(matches, &mut service, &clock)?;
+    // skipping this should be the same as a dry-run.
     run_action(action, &mut service, &clock, &config)
 }

src/main.rs

@@ -1,3 +1,4 @@
+//! Translate CLI args to calls to activity Service.
 use crate::cli_helper;
 use crate::rtw_config::RTWConfig;
 use crate::rtw_core::activity::{Activity, OngoingActivity};
@@ -12,7 +13,10 @@ use clap::ArgMatches;
 
 type ActivityWithId = (ActivityId, Activity);
 
-pub(crate) enum RTWAction {
+/// Describe the action (side-effect) to be made
+///
+/// see `run`
+pub enum RTWAction {
     Cancel(Option<OngoingActivity>),
     Start(OngoingActivity),
     Track(Activity),
@@ -82,7 +86,10 @@ fn run_timeline(
     Ok(RTWAction::Timeline(activities))
 }
 
-pub(crate) fn run<S, Cl>(
+/// Translate CLI args to actions (mostly side-effect free)
+///
+/// It may fetch data from underlying activity storage but it should not write anything.
+pub fn run<S, Cl>(
     matches: ArgMatches,
     service: &mut Service<S>,
     clock: &Cl,
@@ -151,7 +158,8 @@ where
     }
 }
 
-pub(crate) fn run_action<S, Cl>(
+/// Effectively perform the action (side effect).
+pub fn run_action<S, Cl>(
     action: RTWAction,
     service: &mut Service<S>,
     clock: &Cl,

src/rtw_cli.rs

@@ -1,3 +1,4 @@
+//! Config.
 extern crate config;
 
 use self::config::FileFormat;

src/rtw_config.rs

@@ -1,3 +1,5 @@
+//! Activity and OngoingActivity
+
 use crate::rtw_core::datetimew::DateTimeW;
 use crate::rtw_core::durationw::DurationW;
 use crate::rtw_core::Tags;
@@ -93,6 +95,9 @@ impl OngoingActivity {
     }
 }
 
+/// Check intersection between a finished activity and a date
+///
+/// Returns Some(activity) if it intersects else None.
 pub fn intersect(finished: &Activity, datetimew: &DateTimeW) -> Option<Activity> {
     if (&finished.start_time < datetimew) && (datetimew < &finished.stop_time) {
         Some(finished.clone())
@@ -101,6 +106,9 @@ pub fn intersect(finished: &Activity, datetimew: &DateTimeW) -> Option<Activity>
     }
 }
 
+/// Check overlap between 2 finished activities
+///
+/// Returns Some(first) if first activity overlaps with the second else None.
 pub fn overlap(finished: &Activity, other: &Activity) -> Option<Activity> {
     if finished < other {
         intersect(finished, &other.start_time)

src/rtw_core/activity.rs

@@ -1,3 +1,5 @@
+//! Clock abstraction
+
 use crate::rtw_core::datetimew::DateTimeW;
 
 /// Time (absolute or relative)

src/rtw_core/clock.rs

@@ -1,3 +1,4 @@
+//! Newtype on `chrono::Date<Local>`
 use crate::rtw_core::durationw::DurationW;
 use crate::rtw_core::DATETIME_FMT;
 use chrono::{DateTime, Local};

src/rtw_core/datetimew.rs

@@ -1,3 +1,4 @@
+//! Newtype on `chrono::Duration`
 use chrono::Duration;
 use std::fmt;
 use std::fmt::{Error, Formatter};

src/rtw_core/durationw.rs

@@ -1,3 +1,4 @@
+//! Core traits and data structures.
 pub mod activity;
 pub mod clock;
 pub mod datetimew;

src/rtw_core/mod.rs

@@ -1,3 +1,4 @@
+//! A service for activities: abstracts activities queries and modifications.
 use crate::rtw_core::activity::{Activity, OngoingActivity};
 use crate::rtw_core::datetimew::DateTimeW;
 use crate::rtw_core::ActivityId;

src/rtw_core/service.rs

@@ -1,3 +1,4 @@
+//! Storage: abstracts activities storage (file, memory...)
 use crate::rtw_core::activity::{Activity, OngoingActivity};
 use crate::rtw_core::ActivityId;
 use std::error::Error;

src/rtw_core/storage.rs

@@ -1,3 +1,4 @@
+//! Logic above an activity storage
 use crate::rtw_core::activity::{intersect, overlap, Activity, OngoingActivity};
 use crate::rtw_core::datetimew::DateTimeW;
 use crate::rtw_core::service::ActivityService;

src/service.rs

@@ -1,3 +1,4 @@
+//! Time parsing utils.
 use crate::rtw_core::clock::{Clock, Time};
 use anyhow::anyhow;
 use chrono::Local;

src/time_tools.rs

@@ -1,3 +1,4 @@
+//! Timeline display
 use crate::rtw_core::activity::Activity;
 use crate::rtw_core::durationw::DurationW;
 use crate::rtw_core::ActivityId;