94 lines
2.8 KiB
Rust
94 lines
2.8 KiB
Rust
// Documentation represented on the ASG
|
|
//
|
|
// Copyright (C) 2014-2023 Ryan Specialty, LLC.
|
|
//
|
|
// This file is part of TAME.
|
|
//
|
|
// This program is free software: you can redistribute it and/or modify
|
|
// it under the terms of the GNU General Public License as published by
|
|
// the Free Software Foundation, either version 3 of the License, or
|
|
// (at your option) any later version.
|
|
//
|
|
// This program is distributed in the hope that it will be useful,
|
|
// but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
// GNU General Public License for more details.
|
|
//
|
|
// You should have received a copy of the GNU General Public License
|
|
// along with this program. If not, see <http://www.gnu.org/licenses/>.
|
|
|
|
//! Documentation on the ASG.
|
|
//!
|
|
//! TODO: Document TAME's stance on documentation and literate programming,
|
|
//! much of which hasn't been able to be realized over the years.
|
|
|
|
use super::prelude::*;
|
|
use crate::{
|
|
parse::{util::SPair, Token},
|
|
span::Span,
|
|
};
|
|
use std::fmt::Display;
|
|
|
|
/// Documentation string.
|
|
///
|
|
/// TODO: This presently serves as a subject line,
|
|
/// e.g. a description or label,
|
|
/// but will evolve in the future.
|
|
#[derive(Debug, PartialEq, Eq)]
|
|
pub enum Doc {
|
|
/// An (ideally) concise independent clause describing an object.
|
|
IndepClause(SPair),
|
|
|
|
/// Arbitrary text serving as documentation for sibling objects in a
|
|
/// literate style.
|
|
///
|
|
/// TAMER does not presently ascribe any semantic meaning to this text,
|
|
/// and it may even be entirely whitespace.
|
|
/// There are plans to improve upon this in the future.
|
|
///
|
|
/// The intent is for this text to be mixed with sibling objects,
|
|
/// in a style similar to that of literate programming.
|
|
Text(SPair),
|
|
}
|
|
|
|
impl Display for Doc {
|
|
fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
|
|
write!(f, "documentation string")
|
|
}
|
|
}
|
|
|
|
impl Doc {
|
|
/// Document an object using what is ideally a concise independent
|
|
/// clause.
|
|
pub fn new_indep_clause(clause: SPair) -> Self {
|
|
Self::IndepClause(clause)
|
|
}
|
|
|
|
/// Arbitrary text serving as documentation for sibling objects in a
|
|
/// literate style.
|
|
pub fn new_text(text: SPair) -> Self {
|
|
Self::Text(text)
|
|
}
|
|
|
|
pub fn indep_clause(&self) -> Option<SPair> {
|
|
match self {
|
|
Self::IndepClause(spair) => Some(*spair),
|
|
Self::Text(_) => None,
|
|
}
|
|
}
|
|
|
|
pub fn span(&self) -> Span {
|
|
match self {
|
|
Self::IndepClause(spair) | Self::Text(spair) => spair.span(),
|
|
}
|
|
}
|
|
}
|
|
|
|
object_rel! {
|
|
/// Templates may expand into nearly any context,
|
|
/// and must therefore be able to contain just about anything.
|
|
Doc -> {
|
|
// empty
|
|
}
|
|
}
|