add some docs

README.md

@@ -0,0 +1,17 @@
+Simple planet like planet venus but in rust and maintained.
+
+Please see the rustdoc of main.rs for further information.
+
+## todo
+
+* use a nice lib to process the config file
+  * should check whether dirs exists and are writeable
+  * should check whether feed urls can be parsed
+
+## Credits
+
+While writing this, I read and also copied code from:
+
+* [agro](https://docs.rs/crate/agro/0.1.1)
+* [hades](https://github.com/kitallis/hades)
+* [planetrs](https://github.com/djc/planetrs)

README.org

@@ -1,15 +0,0 @@
-Simple planet like planet venus but in rust and maintained.
-
-** todo
-Also see todos in the source files
-
-*** use a nice lib to process the config file
-- should check whether dirs exists and are writeable
-- should check whether feed urls can be parsed
-** Credits
-
-While writing this, I read and also copied code from:
-
-- [[https://docs.rs/crate/agro/0.1.1][agro]]
-- [[https://github.com/kitallis/hades][haded]] by Akshay Gupta
-- [[https://github.com/djc/planetrs][planetrs]] by Vagdish/Adau, Dirkjan Ochtman, Josh Matthews

src/feed_store.rs

@@ -13,6 +13,7 @@ use ureq::http::Response;
 use ureq::Body;
 use url::Url;
 
+/// How many feed entries should be included in the planet
 const ENTRIES_LEN: usize = 10;
 
 #[derive(Deserialize, Serialize, Default)]

src/main.rs

@@ -1,3 +1,25 @@
+//! Planet software to aggregate many feeds into one
+//!
+//! Input feeds are defined in a toml config file given as cmdline
+//! argument. See the [`Config`] struct and the mars.toml.example file.
+//!
+//! The program iterates over all [feed urls], fetches them, stores them in
+//! [feed_dir] and only rebuilds when at least one feed has updates. The
+//! fetcher implements HTTP ETag and LastModified caching.
+//!
+//! During rebuild, all files in [templates_dir] are processed and written to
+//! [out_dir].
+//!
+//! The software is supposed to be run like every 15 minutes.
+//!
+//! Use a reserved (sub)domain to publish the planet! Although this software
+//! tries to sanitize input feeds, there could still be bugs that open the
+//! planets domain to cross-site attacks.
+//!
+//! [templates_dir]: Config#structfield.templates_dir
+//! [feed_dir]: Config#structfield.feed_dir
+//! [out_dir]: Config#structfield.out_dir
+//! [feed urls]: Config#structfield.feeds
 #[macro_use]
 extern crate log;
 
@@ -18,6 +40,7 @@ mod template_engine;
 #[derive(Parser)]
 #[command(author, version, about, long_about = None)]
 struct Args {
+    /// config file in toml format
     #[arg(
         short,
         long,
@@ -28,6 +51,7 @@ struct Args {
     no_fetch: bool,
 }
 
+/// Config to be parsed from toml file given as cmdline option
 #[derive(Deserialize)]
 struct Config {
     /// to be used as part of the fetchers username header
@@ -54,8 +78,13 @@ pub fn to_checked_pathbuf(dir: &str) -> PathBuf {
     dir
 }
 
+/// Config for one individual input feed
+///
+/// This is a separate struct in case one wants to configure additional
+/// information in the future.
 #[derive(Deserialize)]
 struct FeedConfig {
+    /// url of an ATOM, RSS or Json feed
     url: String,
 }