Add builder convenience method to Group (#44)

* Add builder convenience method to Group
* Add more detailed documentation on `Group::builder`
* Use `Group::builder` within `Group::new`

---------

Co-authored-by: Phantomical <phantom@lynches.ca>

Author: daniel-levin

perf-event/src/group.rs

@@ -99,14 +99,36 @@ impl Group {
     /// on any CPU. If you need to build a `Group` with different settings you
     /// will need to use [`Builder::build_group`].
     pub fn new() -> io::Result<Group> {
-        Builder::new(Software::DUMMY)
-            .read_format(
-                ReadFormat::GROUP
-                    | ReadFormat::TOTAL_TIME_ENABLED
-                    | ReadFormat::TOTAL_TIME_RUNNING
-                    | ReadFormat::ID,
-            )
-            .build_group()
+        Self::builder().build_group()
+    }
+
+    /// Construct a [Builder] preconfigured for creating a `Group`.
+    ///
+    /// Specifically, this creates a builder with the [`Software::DUMMY`] event
+    /// and with [`read_format`] set to `GROUP | ID | TOTAL_TIME_ENABLED |
+    /// TOTAL_TIME_RUNNING`. If you override [`read_format`] you will need to
+    /// ensure that [`ReadFormat::GROUP`] is set, otherwise [`build_group`] will
+    /// return an error.
+    ///
+    /// Note that any counter added to this group must observe the same set of
+    /// CPUs and processes as the group itself. That means if you configure the
+    /// group to observe a single CPU then the members of the group must also be
+    /// configured to only observe a single CPU, the same applies when choosing
+    /// target processes. Failing to follow this will result in an error when
+    /// adding the counter to the group.
+    ///
+    /// [`read_format`]: Builder::read_format
+    /// [`build_group`]: Builder::build_group
+    pub fn builder() -> Builder<'static> {
+        let mut builder = Builder::new(Software::DUMMY);
+        builder.read_format(
+            ReadFormat::GROUP
+                | ReadFormat::TOTAL_TIME_ENABLED
+                | ReadFormat::TOTAL_TIME_RUNNING
+                | ReadFormat::ID,
+        );
+
+        builder
     }
 
     /// Access the internal counter for this group.