X-Git-Url: https://git.ladys.computer/CGirls/blobdiff_plain/ffe1bd11b097144214c47a568705112dffebdfa4..1d51bcca18b99d2b82d388ca8832ac85c539fdd6:/request.h

diff --git a/request.h b/request.h
index 3ff77e2..7e95fbe 100644
--- a/request.h
+++ b/request.h
@@ -14,38 +14,38 @@
  ** § Types
  **////////////////////////////////////////////////////////////////////
 /**
- ** ❦ `enum cgirls_mtype´
+ ** ❦ `enum ⸤cgirls_mtype⸥´
  **
- ** The `cgirls_mtype´ enumeration is used to indicate recognized
+ ** The `⸤cgirls_mtype⸥´ enumeration is used to indicate recognized
  ** mediatype extensions.
  **/
 enum cgirls_mtype : unsigned char {
 /**
- ** The value `cgirls_mtype_any´ indicates no mediatype preference.
+ ** The value `⟨cgirls_mtype_any⟩´ indicates no mediatype preference.
  **/
 	cgirls_mtype_any = 0,
 
 /**
- ** The value `cgirls_mtype_txt´ indicates a preference for
+ ** The value `⟨cgirls_mtype_txt⟩´ indicates a preference for
  ** `text/plain´ content.
  **/
 	cgirls_mtype_txt = 1,
 
 /**
- ** The value `cgirls_mtype_htm´ indicates a preference for
+ ** The value `⟨cgirls_mtype_htm⟩´ indicates a preference for
  ** `text/html´ content.
  **/
 	cgirls_mtype_htm = 2,
 
 /**
- ** The value `cgirls_mtype_xml´ indicates a preference for
+ ** The value `⟨cgirls_mtype_xml⟩´ indicates a preference for
  ** `application/xml´ content, ideally with an `<?xml-stylesheet?>´
  ** processing instruction.
  **/
 	cgirls_mtype_xml = 3,
 
 /**
- ** The value `cgirls_mtype_rdf´ indicates a preference for
+ ** The value `⟨cgirls_mtype_rdf⟩´ indicates a preference for
  ** `application/rdf+xml´ content.
  **/
 	cgirls_mtype_rdf = 4,
@@ -54,53 +54,53 @@ enum cgirls_mtype : unsigned char {
 typedef enum cgirls_mtype cgirls_mtype;
 
 /**
- ** ❦ `enum cgirls_vb´
+ ** ❦ `enum ⸤cgirls_vb⸥´
  **
- ** The `cgirls_vb´ enumeration is used to indicate recognized verbs
+ ** The `⸤cgirls_vb⸥´ enumeration is used to indicate recognized verbs
  ** for requests.
  **/
 enum cgirls_vb : unsigned char {
 
 /**
- ** The value `cgirls_vb_unknown´ indicates an unknown or unspecified
+ ** The value `⟨cgirls_vb_unknown⟩´ indicates an unknown or unspecified
  ** verb.
  **/
 	cgirls_vb_unknown = 0,
 
 /**
- ** The value `cgirls_vb_index´ indicates a request for an index of
+ ** The value `⟨cgirls_vb_index⟩´ indicates a request for an index of
  ** projects.
  **/
 	cgirls_vb_index = 1,
 
 /**
- ** The value `cgirls_vb_branches´ indicates a request for an index of
- ** branches in a given project. The value `cgirls_vb_tags´ indicates a
- ** request for an index of tags.
+ ** The value `⟨cgirls_vb_branches⟩´ indicates a request for an index
+ ** of branches in a given project. The value `⟨cgirls_vb_tags⟩´
+ ** indicates a request for an index of tags.
  **/
 	// cgirls_vb_branches = ??,
 	// cgirls_vb_tags = ??,
 
 /**
- ** The value `cgirls_vb_show´ indicates a request for an object in a
- ** human‐readable manner. The value `cgirls_vb_raw´ indicates a
+ ** The value `⟨cgirls_vb_show⟩´ indicates a request for an object in a
+ ** human‐readable manner. The value `⟨cgirls_vb_raw⟩´ indicates a
  ** request for the raw contents of an object. The value
- ** `cgirls_vb_blame´ indicates a request for a blame of a commit.
+ ** `⟨cgirls_vb_blame⟩´ indicates a request for a blame of a commit.
  **/
 	cgirls_vb_show = 2,
 	// cgirls_vb_raw = ??,
 	// cgirls_vb_blame = ??,
 
 /**
- ** The value `cgirls_vb_index´ indicates a request for a diff between
- ** two commits.
+ ** The value `⟨cgirls_vb_index⟩´ indicates a request for a diff
+ ** between two commits.
  **/
 	// cgirls_vb_diff = ??,
 
 /**
- ** The values `cgirls_vb_log´, `cgirls_vb_shortlog´, `cgirls_vb_atom´,
- ** and `cgirls_vb_patch´ indicate requests for logs of a number of
- ** commits in various formats.
+ ** The values `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
+ ** `⟨cgirls_vb_atom⟩´, and `⟨cgirls_vb_patch⟩´ indicate requests for
+ ** logs of a number of commits in various formats.
  **/
 	// cgirls_vb_log = ??,
 	// cgirls_vb_shortlog = ??,
@@ -114,30 +114,30 @@ enum cgirls_vb : unsigned char {
  **
  ** Verbs can be categorized into a few distinct classes :—
  **
- ** • Verbs which do not require a project :— `cgirls_vb_index´.
+ ** • Verbs which do not require a project :— `⟨cgirls_vb_index⟩´.
  **
  ** • Verbs which require a project, but not a revspec :—
- ** `cgirls_vb_branches´, `cgirls_vb_tags´.
+ ** `⟨cgirls_vb_branches⟩´, `⟨cgirls_vb_tags⟩´.
  **
  ** • Verbs which request information about a single object :—
- ** `cgirls_vb_show´, `cgirls_vb_raw´, `cgirls_vb_blame´.
+ ** `⟨cgirls_vb_show⟩´, `⟨cgirls_vb_raw⟩´, `⟨cgirls_vb_blame⟩´.
  **
- ** • Verbs which compare two commits :— `cgirls_vb_diff´.
+ ** • Verbs which compare two commits :— `⟨cgirls_vb_diff⟩´.
  **
  ** • Verbs which produce information about an open‐ended number of
- ** commits :— `cgirls_vb_log´, `cgirls_vb_shortlog´,
- ** `cgirls_vb_atom´, `cgirls_vb_patch´.
+ ** commits :— `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
+ ** `⟨cgirls_vb_atom⟩´, `⟨cgirls_vb_patch⟩´.
  **/
 };
 typedef enum cgirls_vb cgirls_vb;
 
 /**
- ** ❦ `struct cgirls_req_status´
+ ** ❦ `struct ⸤cgirls_req_status⸥´
  **
- ** The struct `cgirls_req_status´ wraps a status code and message for
- ** a response.
+ ** The struct `⸤cgirls_req_status⸥´ wraps a status code and message
+ ** for a response.
  **
- ** The `.message´ is only significant if `.code´ is not `200´.
+ ** The `⟨.message⟩´ is only significant if `⟨.code⟩´ is not `200´.
  **/
 typedef struct cgirls_req_status cgirls_req_status;
 struct cgirls_req_status {
@@ -146,16 +146,19 @@ struct cgirls_req_status {
 };
 
 /**
- ** ❦ `struct cgirls_req´
+ ** ❦ `struct ⸤cgirls_req⸥´
  **
- ** The struct `cgirls_req´ represents a request.
+ ** The struct `⸤cgirls_req⸥´ represents a request.
  **
  ** Requests must have a verb, may specify a mediatype extension, and
- ** might also reference a project, revspec, and subpath.
+ ** might also reference a project, revspec, and subpath. The value of
+ ** `⟨.subpath⟩´, if not `⟨nullptr⟩´, must be a `⟨nullptr⟩´‐terminated
+ ** array of strings.
  **
  ** All requests have a status, which is used to express request
- ** validity. If `.status.code´ is not `200´, the request is invalid
- ** and a response with the associated code and message is recommended.
+ ** validity. If `⟨.status⟩⟨.code⟩´ is not `200´, the request is
+ ** invalid and a response with the associated code and message is
+ ** recommended.
  **/
 typedef struct cgirls_req cgirls_req;
 struct cgirls_req {
@@ -172,14 +175,14 @@ struct cgirls_req {
  ** § Functions
  **////////////////////////////////////////////////////////////////////
 /**
- ** ❦ `cgirls_req cgirls_path·to·req(char const*const)´
+ ** ❦ `⸤cgirls_req⸥ ⟨cgirls_path·to·req⟩(⸤char const*const⸥)´
  **
- ** The `cgirls_path·to·req´ function takes a path string (such as one
- ** provided by the C·G·I `PATH_INFO´ environment variable) and returns
- ** a `cgirls_req´ which represents its semantics.
+ ** The `⟨cgirls_path·to·req⟩´ function takes a path string (such as
+ ** one provided by the C·G·I `⟨PATH_INFO⟩´ environment variable) and
+ ** returns a `⸤cgirls_req⸥´ which represents its semantics.
  **
  ** This resulting struct contains a lot of dynamically‐allocated data,
- ** so it ☞︎must☜︎ be freed with `cgirls_req·free´ after use.
+ ** so it ☞︎must☜︎ be freed with `⟨cgirls_req·free⟩´ after use.
  **
  ** Maximally, the path string is processed according to the following
  ** form :—
@@ -191,32 +194,35 @@ struct cgirls_req {
  ** extension). Not all components necessarily need to be specified,
  ** and not all possible values are valid or meaningful.
  **
- ** In case of an error, `.status.code´ on the returned `cgirls_req´
- ** will be some·thing other than `200´.
+ ** In case of an error, `⟨.status⟩⟨.code⟩´ on the returned
+ ** `⸤cgirls_req⸥´ will be some·thing other than `200´.
  **/
 cgirls_req cgirls_path·to·req(char const*const);
 
 /**
- ** ❦ `void cgirls_req·free(cgirls_req)´
+ ** ❦ `⸤void⸥ ⟨cgirls_req·free⟩(⸤cgirls_req⸥)´
  **
- ** The `cgirls_req·free´ function frees up any dynamically‐allocated
- ** memory in the provided `cgirls_req´, assuming that it was created
- ** with `cgirls_path·to·req´ or similar.
+ ** The `⟨cgirls_req·free⟩´ function frees up any dynamically‐allocated
+ ** memory in the provided `⸤cgirls_req⸥´, assuming that it was created
+ ** with `⟨cgirls_path·to·req⟩´ or similar.
  **/
 void cgirls_req·free(cgirls_req);
 
 /**
- ** ❦ `char* cgirls_req·to·path(cgirls_req)´
+ ** ❦ `⸤char*⸥ ⟨cgirls_req·to·path⟩(⸤cgirls_req⸥)´
  **
- ** The `cgirls_req·to·path´ function does the reverse of
- ** `cgirls_path·to·req´: It takes in a `cgirls_req´ structure and
+ ** The `⟨cgirls_req·to·path⟩´ function does the reverse of
+ ** `⟨cgirls_path·to·req⟩´: It takes in a `⸤cgirls_req⸥´ struct and
  ** returns the canonical path string which represents it.
  **
- ** All possible `cgirls_req´s have a canonical string representation;
- ** `cgirls_req·to·path´ will only return `nullptr´ if it
+ ** All possible `⸤cgirls_req⸥´s have a canonical string
+ ** representation; `⟨cgirls_req·to·path⟩´ will only return `⟨nullptr⟩´
+ ** if it fails to allocate memory while constructing the resulting
+ ** string. Return values are dynamically allocated and must be
+ ** manually freed with `⟨free⟩´.
  **
- ** It is worth noting that, if the `.project´ is the null pointer, the
- ** canonical path string will always be the empty string.
+ ** It is worth noting that, if the `⟨.project⟩´ is the null pointer,
+ ** the canonical path string will always be the empty string.
  **/
 char* cgirls_req·to·path(cgirls_req);