Skip to content

Commit 9c7e071

Browse files
author
rwh
committed
improve comments
1 parent 1ace9e8 commit 9c7e071

File tree

1 file changed

+35
-8
lines changed

1 file changed

+35
-8
lines changed

lib/compsci/unix_path.rb

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,35 @@
11
module CompSci
22

3+
# Overview
4+
# ===
5+
#
36
# This is a simplification of common Unix paths, as used in Linux, OS X, etc.
47
# It is intended to cover 99.9% of the "good use cases" and "best practices"
58
# for path and filename conventions on Unix filesystems.
6-
9+
#
710
# Some primary distinctions:
811
# 1. Absolute vs Relative paths
9-
# 2. File vs directory
10-
12+
# 2. File vs Directory
13+
#
1114
# Absolute paths are indicated with a leading slash (/)
15+
# e.g. /etc/passwd or /home/user/.emacs
16+
#
1217
# Relative paths are primarily indicated with a leading dot-slash (./)
1318
# or they may omit the leading ./ for brevity.
19+
# e.g. ./a.out or path/to/file.txt
1420

21+
# Directories and Files
22+
# ===
23+
#
1524
# In string form, directories are indicated with a trailing slash (/).
1625
# With no trailing slash, the last segment of a path is treated as a filename.
26+
#
1727
# Internally, there is a @filename string, and if it is empty, this has
1828
# semantic meaning: the UnixPath is a directory.
1929

30+
# Basename and Extension
31+
# ===
32+
#
2033
# For nonempty @filename, it may be further broken down into basename
2134
# and extension, with an overly simple rule:
2235
#
@@ -34,14 +47,22 @@ module CompSci
3447
# If @filename is empty, basename and extension are nil.
3548

3649
# Internal Representation
50+
# ===
51+
#
3752
# * abs: boolean indicating abspath vs relpath
3853
# * subdirs: array of strings, like %w[home user docs]
3954
# * filename: string, possibly empty
4055

56+
# Strings
57+
# ===
58+
#
4159
# Consume a string path with UnixPath.parse, creating a UnixPath instance.
4260
# Emit a string with UnixPath#to_s.
43-
# Relative paths are emitted with leading ./
61+
# Relative paths are emitted with leading dot-slash (./)
4462

63+
# Creation
64+
# ===
65+
#
4566
# Combine path components with `slash`, aliased to /, yielding a UnixPath
4667
# * UnixPath.parse('/etc') / 'systemd' / 'system'
4768
# * UnixPath.parse('/etc').slash('passwd')
@@ -53,6 +74,9 @@ module CompSci
5374
# Or construct by hand:
5475
# * UnixPath.new(abs: true, subdirs: %w[etc systemd system])
5576

77+
# Implementation Details
78+
# ===
79+
#
5680
# Most of UnixPath is implemented via PathMixin and its FactoryMethods
5781
# These modules are mixed in to base classes ImmutablePath and MutablePath.
5882
# ImmutablePath is based on Ruby's Data.define, using Data.with for efficient
@@ -62,11 +86,14 @@ module CompSci
6286
# This pattern of assigning a constant can allow you to create your own Path
6387
# in your own context. e.g. MyPath = CompSci::MutablePath
6488

65-
# Note that these are logical paths and have no connection to any filesystem.
89+
# Nota Bene
90+
# ===
91+
#
92+
# These are logical paths and have no connection to any filesystem.
6693
# This library never looks at the local filesystem that it runs on.
67-
68-
# ImmutablePath and MutablePath both mix in this module via include
69-
# N.B. @ivar references will not work with Data.define, so use self.ivar
94+
# ImmutablePath and MutablePath both mix in this module via `include`.
95+
# They also pull in class methods via `extend` via the `included` hook.
96+
# @ivar references will not work with Data.define, so use self.ivar
7097
module PathMixin
7198
include Comparable
7299

0 commit comments

Comments
 (0)