From 779cef6105c8eea8dfc35a4e662510241921dcac Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=90=D0=BD=D0=B4=D1=80=D0=B5=D0=B9=20=D0=9B=D1=83=D1=85?=
=?UTF-8?q?=D0=BD=D0=BE=D0=B2?= <loukhnov@lotes-tm.ru>
Date: Mon, 18 Nov 2024 17:39:04 +0300
Subject: [PATCH] Create godoc-friendly examples
Move tests from the diskfs.go global comment section and
update them as they are slightly out of date.
---
diskfs.go | 92 ------------------------------
example_test.go | 145 ++++++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 145 insertions(+), 92 deletions(-)
create mode 100644 example_test.go
diff --git a/diskfs.go b/diskfs.go
index f0952a09..75fa5367 100644
--- a/diskfs.go
+++ b/diskfs.go
@@ -8,98 +8,6 @@
// This is not intended as a replacement for operating system filesystem and disk drivers. Instead,
// it is intended to make it easy to work with partitions, partition tables and filesystems directly
// without requiring operating system mounts.
-//
-// Some examples:
-//
-// 1. Create a disk image of size 10MB with a FAT32 filesystem spanning the entire disk.
-//
-// import diskfs "github.com/diskfs/go-diskfs"
-// size := 10*1024*1024 // 10 MB
-//
-// diskImg := "/tmp/disk.img"
-// disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-// fs, err := disk.CreateFilesystem(0, diskfs.TypeFat32)
-//
-// 2. Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
-// of size 10MB filled with a FAT32 filesystem.
-//
-// import diskfs "github.com/diskfs/go-diskfs"
-//
-// diskSize := 10*1024*1024 // 10 MB
-//
-// diskImg := "/tmp/disk.img"
-// disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-// table := &mbr.Table{
-// LogicalSectorSize: 512,
-// PhysicalSectorSize: 512,
-// Partitions: []*mbr.Partition{
-// {
-// Bootable: false,
-// Type: Linux,
-// Start: 2048,
-// Size: 20480,
-// },
-// },
-// }
-//
-// fs, err := disk.CreateFilesystem(1, diskfs.TypeFat32)
-//
-// 3. Create a disk of size 20MB with a GPT partition table, a single partition beginning at block 2048 (1MB),
-// of size 10MB, and fill with the contents from the 10MB file "/root/contents.dat"
-//
-// import diskfs "github.com/diskfs/go-diskfs"
-//
-// diskSize := 10*1024*1024 // 10 MB
-//
-// diskImg := "/tmp/disk.img"
-// disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-// table := &gpt.Table{
-// LogicalSectorSize: 512,
-// PhysicalSectorSize: 512,
-// Partitions: []*gpt.Partition{
-// {
-// LogicalSectorSize: 512,
-// PhysicalSectorSize: 512,
-// ProtectiveMBR: true,
-// },
-// },
-// }
-//
-// f, err := os.Open("/root/contents.dat")
-// written, err := disk.WritePartitionContents(1, f)
-//
-// 4. Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
-// of size 10MB filled with a FAT32 filesystem, and create some directories and files in that filesystem.
-//
-// import diskfs "github.com/diskfs/go-diskfs"
-//
-// diskSize := 10*1024*1024 // 10 MB
-//
-// diskImg := "/tmp/disk.img"
-// disk := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
-//
-// table := &mbr.Table{
-// LogicalSectorSize: 512,
-// PhysicalSectorSize: 512,
-// Partitions: []*mbr.Partition{
-// {
-// Bootable: false,
-// Type: Linux,
-// Start: 2048,
-// Size: 20480,
-// },
-// },
-// }
-//
-// fs, err := disk.CreateFilesystem(1, diskfs.TypeFat32)
-// err := fs.Mkdir("/FOO/BAR")
-// rw, err := fs.OpenFile("/FOO/BAR/AFILE.EXE", os.O_CREATE|os.O_RDRWR)
-// b := make([]byte, 1024, 1024)
-// rand.Read(b)
-// err := rw.Write(b)
package diskfs
import (
diff --git a/example_test.go b/example_test.go
new file mode 100644
index 00000000..6b99bac2
--- /dev/null
+++ b/example_test.go
@@ -0,0 +1,145 @@
+package diskfs_test
+
+import (
+ "crypto/rand"
+ "log"
+ "os"
+
+ diskfs "github.com/diskfs/go-diskfs"
+ "github.com/diskfs/go-diskfs/disk"
+ "github.com/diskfs/go-diskfs/filesystem"
+ "github.com/diskfs/go-diskfs/partition/gpt"
+ "github.com/diskfs/go-diskfs/partition/mbr"
+)
+
+func check(err error) {
+ if err != nil {
+ log.Fatal(err)
+ }
+}
+
+func unused(_ ...any) {
+}
+
+// Create a disk image of size 10MB with a FAT32 filesystem spanning the entire disk.
+func ExampleCreate_fat32() {
+ var size int64 = 10 * 1024 * 1024 // 10 MB
+
+ diskImg := "/tmp/disk.img"
+ defer os.Remove(diskImg)
+ theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+ fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+ Partition: 0,
+ FSType: filesystem.TypeFat32,
+ })
+ check(err)
+ unused(fs)
+}
+
+// Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
+// of size 10MB filled with a FAT32 filesystem.
+func ExampleCreate_mbr() {
+ var size int64 = 20 * 1024 * 1024 // 20 MB
+
+ diskImg := "/tmp/disk.img"
+ defer os.Remove(diskImg)
+ theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+ table := &mbr.Table{
+ LogicalSectorSize: 512,
+ PhysicalSectorSize: 512,
+ Partitions: []*mbr.Partition{
+ {
+ Bootable: false,
+ Type: mbr.Linux,
+ Start: 2048,
+ Size: 20480,
+ },
+ },
+ }
+
+ check(theDisk.Partition(table))
+
+ fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+ Partition: 1,
+ FSType: filesystem.TypeFat32,
+ })
+ check(err)
+ unused(fs)
+}
+
+// Create a disk of size 20MB with a GPT partition table, a single partition beginning at block 2048 (1MB), of size 10MB, and fill with the contents from the 10MB file "/root/contents.dat"
+func ExampleCreate_gpt() {
+ var size int64 = 20 * 1024 * 1024 // 20 MB
+
+ diskImg := "/tmp/disk.img"
+ defer os.Remove(diskImg)
+ theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+ table := &gpt.Table{
+ LogicalSectorSize: 512,
+ PhysicalSectorSize: 512,
+ ProtectiveMBR: true,
+ Partitions: []*gpt.Partition{
+ {
+ Start: 1 * 1024 * 1024 / 512,
+ Size: 10 * 1024 * 1024,
+ },
+ },
+ }
+
+ check(theDisk.Partition(table))
+
+ f, err := os.Open("/root/contents.dat")
+ check(err)
+
+ written, err := theDisk.WritePartitionContents(1, f)
+ check(err)
+ unused(written)
+}
+
+// Create a disk of size 20MB with an MBR partition table, a single partition beginning at block 2048 (1MB),
+// of size 10MB filled with a FAT32 filesystem, and create some directories and files in that filesystem.
+func ExampleCreate_fat32WithDirsAndFiles() {
+ var size int64 = 20 * 1024 * 1024 // 20 MB
+
+ diskImg := "/tmp/disk.img"
+ defer os.Remove(diskImg)
+ theDisk, _ := diskfs.Create(diskImg, size, diskfs.Raw, diskfs.SectorSizeDefault)
+
+ table := &mbr.Table{
+ LogicalSectorSize: 512,
+ PhysicalSectorSize: 512,
+ Partitions: []*mbr.Partition{
+ {
+ Bootable: false,
+ Type: mbr.Linux,
+ Start: 2048,
+ Size: 20480,
+ },
+ },
+ }
+
+ check(theDisk.Partition(table))
+
+ fs, err := theDisk.CreateFilesystem(disk.FilesystemSpec{
+ Partition: 1,
+ FSType: filesystem.TypeFat32,
+ })
+ check(err)
+
+ err = fs.Mkdir("/FOO/BAR")
+ check(err)
+
+ rw, err := fs.OpenFile("/FOO/BAR/AFILE.EXE", os.O_CREATE|os.O_RDWR)
+ check(err)
+ b := make([]byte, 1024)
+
+ _, err = rand.Read(b)
+ check(err)
+
+ written, err := rw.Write(b)
+ check(err)
+ unused(written)
+}