📝 Expose Go docstrings in JSON schemas

jsonschema.go

@@ -24,6 +24,7 @@ func makeJSONSchema(t any, yaml bool) string {
 	if yaml {
 		selectedReflector = yamlReflector
 	}
+	selectedReflector.AddGoComments("github.com/ortfo/db", "./")
 	schema := selectedReflector.Reflect(t)
 	setSchemaId(schema)
 	out, err := json.MarshalIndent(schema, "", "  ")

packages/python/ortfodb/configuration.py

@@ -181,13 +181,19 @@ def to_dict(self) -> dict:
 
 
 class Configuration:
+    """Configuration represents what the ortfodb.yaml configuration file describes."""
+
     build_metadata_file: str
     exporters: Optional[Dict[str, Dict[str, Any]]]
+    """Exporter-specific configuration. Maps exporter names to their configuration."""
+
     extract_colors: ExtractColors
     make_gifs: MakeGifs
     make_thumbnails: MakeThumbnails
     media: Media
     projects_at: str
+    """Path to the directory containing all projects. Must be absolute."""
+
     scattered_mode_folder: str
     tags: Tags
     technologies: Technologies

packages/python/ortfodb/database.py

@@ -45,11 +45,22 @@ def from_dict(f: Callable[[Any], T], x: Any) -> Dict[str, T]:
 
 
 class Attributes:
+    """MediaAttributes stores which HTML attributes should be added to the media."""
+
     autoplay: bool
+    """Controlled with attribute character > (adds)"""
+
     controls: bool
+    """Controlled with attribute character = (removes)"""
+
     loop: bool
+    """Controlled with attribute character ~ (adds)"""
+
     muted: bool
+    """Controlled with attribute character > (adds)"""
+
     playsinline: bool
+    """Controlled with attribute character = (adds)"""
 
     def __init__(self, autoplay: bool, controls: bool, loop: bool, muted: bool, playsinline: bool) -> None:
         self.autoplay = autoplay
@@ -79,6 +90,8 @@ def to_dict(self) -> dict:
 
 
 class Colors:
+    """ColorPalette reprensents the object in a Work's metadata.colors."""
+
     primary: str
     secondary: str
     tertiary: str
@@ -105,9 +118,16 @@ def to_dict(self) -> dict:
 
 
 class Dimensions:
+    """ImageDimensions represents metadata about a media as it's extracted from its file."""
+
     aspect_ratio: float
+    """width / height"""
+
     height: int
+    """Height in pixels"""
+
     width: int
+    """Width in pixels"""
 
     def __init__(self, aspect_ratio: float, height: int, width: int) -> None:
         self.aspect_ratio = aspect_ratio
@@ -149,21 +169,29 @@ def to_dict(self) -> dict:
 class BlockElement:
     alt: str
     analyzed: bool
+    """whether the media has been analyzed"""
+
     anchor: str
     attributes: Attributes
     caption: str
     colors: Colors
     content: str
+    """html"""
+
     content_type: str
     dimensions: Dimensions
     dist_source: str
     duration: float
+    """in seconds"""
+
     has_sound: bool
     id: str
     index: int
     online: bool
     relative_source: str
     size: int
+    """in bytes"""
+
     text: str
     thumbnails: Thumbnails
     thumbnails_built_at: str
@@ -284,6 +312,7 @@ def to_dict(self) -> dict:
 
 class DatabaseMetadataClass:
     partial: bool
+    """Partial is true if the database was not fully built."""
 
     def __init__(self, partial: bool) -> None:
         self.partial = partial
@@ -367,6 +396,8 @@ def to_dict(self) -> dict:
 
 
 class DatabaseValue:
+    """AnalyzedWork represents a complete work, with analyzed mediae."""
+
     built_at: str
     content: Dict[str, ContentValue]
     description_hash: str

packages/python/ortfodb/technologies.py

@@ -22,9 +22,16 @@ def to_class(c: Type[T], x: Any) -> dict:
 class Technology:
     aliases: List[str]
     autodetect: List[str]
+    """Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a
+    free-form unquoted string and PATH is a filepath relative to the work folder.
+    If CONTENT is found in PATH, we consider that technology to be used in the work.
+    """
     by: str
     description: str
     files: List[str]
+    """Files contains a list of gitignore-style patterns. If the work contains any of the
+    patterns specified, we consider that technology to be used in the work.
+    """
     learn_more_at: str
     name: str
     slug: str

packages/rust/src/configuration.rs

@@ -14,11 +14,13 @@
 use serde::{Serialize, Deserialize};
 use std::collections::HashMap;
 
+/// Configuration represents what the ortfodb.yaml configuration file describes.
 #[derive(Serialize, Deserialize)]
 pub struct Configuration {
     #[serde(rename = "build metadata file")]
     pub build_metadata_file: String,
 
+    /// Exporter-specific configuration. Maps exporter names to their configuration.
     pub exporters: Option<HashMap<String, HashMap<String, Option<serde_json::Value>>>>,
 
     #[serde(rename = "extract colors")]
@@ -32,6 +34,7 @@ pub struct Configuration {
 
     pub media: Media,
 
+    /// Path to the directory containing all projects. Must be absolute.
     #[serde(rename = "projects at")]
     pub projects_at: String,
 

packages/rust/src/database.rs

@@ -16,6 +16,7 @@ use std::collections::HashMap;
 
 pub type Database = HashMap<String, DatabaseValue>;
 
+/// AnalyzedWork represents a complete work, with analyzed mediae.
 #[derive(Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct DatabaseValue {
@@ -49,6 +50,7 @@ pub struct ContentValue {
 pub struct BlockElement {
     pub alt: String,
 
+    /// whether the media has been analyzed
     pub analyzed: bool,
 
     pub anchor: String,
@@ -59,6 +61,7 @@ pub struct BlockElement {
 
     pub colors: Colors,
 
+    /// html
     pub content: String,
 
     pub content_type: String,
@@ -67,6 +70,7 @@ pub struct BlockElement {
 
     pub dist_source: String,
 
+    /// in seconds
     pub duration: f64,
 
     pub has_sound: bool,
@@ -79,6 +83,7 @@ pub struct BlockElement {
 
     pub relative_source: String,
 
+    /// in bytes
     pub size: i64,
 
     pub text: String,
@@ -95,20 +100,27 @@ pub struct BlockElement {
     pub url: String,
 }
 
+/// MediaAttributes stores which HTML attributes should be added to the media.
 #[derive(Serialize, Deserialize)]
 pub struct Attributes {
+    /// Controlled with attribute character > (adds)
     pub autoplay: bool,
 
+    /// Controlled with attribute character = (removes)
     pub controls: bool,
 
+    /// Controlled with attribute character ~ (adds)
     #[serde(rename = "loop")]
     pub attributes_loop: bool,
 
+    /// Controlled with attribute character > (adds)
     pub muted: bool,
 
+    /// Controlled with attribute character = (adds)
     pub playsinline: bool,
 }
 
+/// ColorPalette reprensents the object in a Work's metadata.colors.
 #[derive(Serialize, Deserialize)]
 pub struct Colors {
     pub primary: String,
@@ -118,13 +130,17 @@ pub struct Colors {
     pub tertiary: String,
 }
 
+/// ImageDimensions represents metadata about a media as it's extracted from its file.
 #[derive(Serialize, Deserialize)]
 #[serde(rename_all = "camelCase")]
 pub struct Dimensions {
+    /// width / height
     pub aspect_ratio: f64,
 
+    /// Height in pixels
     pub height: i64,
 
+    /// Width in pixels
     pub width: i64,
 }
 
@@ -165,5 +181,6 @@ pub struct Metadata {
 #[derive(Serialize, Deserialize)]
 #[serde(rename_all = "PascalCase")]
 pub struct DatabaseMetadataClass {
+    /// Partial is true if the database was not fully built.
     pub partial: bool,
 }

packages/rust/src/technologies.rs

@@ -19,12 +19,17 @@ pub type Technologies = Vec<Technology>;
 pub struct Technology {
     pub aliases: Vec<String>,
 
+    /// Autodetect contains an expression of the form 'CONTENT in PATH' where CONTENT is a
+    /// free-form unquoted string and PATH is a filepath relative to the work folder.
+    /// If CONTENT is found in PATH, we consider that technology to be used in the work.
     pub autodetect: Vec<String>,
 
     pub by: String,
 
     pub description: String,
 
+    /// Files contains a list of gitignore-style patterns. If the work contains any of the
+    /// patterns specified, we consider that technology to be used in the work.
     pub files: Vec<String>,
 
     #[serde(rename = "learn more at")]

packages/typescript/src/configuration.ts

@@ -7,13 +7,22 @@
 // These functions will throw an error if the JSON doesn't
 // match the expected interface, even if the JSON is valid.
 
+/**
+ * Configuration represents what the ortfodb.yaml configuration file describes.
+ */
 export interface Configuration {
-    "build metadata file":   string;
-    exporters?:              { [key: string]: { [key: string]: any } };
-    "extract colors":        ExtractColors;
-    "make gifs":             MakeGifs;
-    "make thumbnails":       MakeThumbnails;
-    media:                   Media;
+    "build metadata file": string;
+    /**
+     * Exporter-specific configuration. Maps exporter names to their configuration.
+     */
+    exporters?:        { [key: string]: { [key: string]: any } };
+    "extract colors":  ExtractColors;
+    "make gifs":       MakeGifs;
+    "make thumbnails": MakeThumbnails;
+    media:             Media;
+    /**
+     * Path to the directory containing all projects. Must be absolute.
+     */
     "projects at":           string;
     "scattered mode folder": string;
     tags:                    Tags;