Add documentation for roles and classes

kasei commented 9 years ago

There are many roles and classes in Attean that are not documented. Most roles and classes that are not currently documented share a lot of description/boilerplate POD with roles/classes that already exist. See any .pod file in lib/Attean/API/ for an example of a documented role. Similar .pod files are needed for all roles defined under Attean::API.

The documentation for roles contained under Attean::API follows a template for describing the role and its attributes, required methods, and provided methods.

Documentation for classes follows a similar template describing consumed roles, constructor(s) API, attributes, and methods.

This should be a very easy task for many of the roles/classes that are missing documentation.

kasei commented 9 years ago

Here are some example templates:

This is a list of all classes and roles currently in the Attean codebase. They're checked off if they have POD, and not checked off if they either don't have POD or have POD but it hasn't been checked to be aligned with the new POD templates.

Load-points and Utilities

[x] Attean
[x] Attean::API
[x] Attean::Algebra (only a file, not a class)
[x] Attean::Expression (only a file, not a class)
[x] Attean::RDF

API Roles

[x] Attean::API::Binding
[x] Attean::API::Expression
[x] Attean::API::Iterator
[x] Attean::API::Model
[x] Attean::API::Parser
[x] Attean::API::Serializer
[x] Attean::API::Store
[x] Attean::API::Term
[x] Attean::API::Query
[x] Attean::API::AbbreviatingSerializer
[x] Attean::API::TermSerializer
[x] Attean::API::ResultSerializer
[x] Attean::API::QuadSerializer
[x] Attean::API::TripleSerializer
[x] Attean::API::MixedStatementSerializer
[x] Attean::API::AppendableSerializer
[x] Attean::API::PullParser
[x] Attean::API::PushParser
[x] Attean::API::AtOnceParser
[x] Attean::API::AbbreviatingParser
[x] Attean::API::TermParser
[x] Attean::API::TripleParser
[x] Attean::API::QuadParser
[x] Attean::API::MixedStatementParser
[x] Attean::API::ResultParser
[x] Attean::API::AggregateExpression
[ ] Attean::API::Algebra
[ ] Attean::API::BinaryExpression
[ ] Attean::API::BinaryQueryTree
[x] Attean::API::Blank
[x] Attean::API::BlankOrIRI
[x] Attean::API::BulkUpdatableModel
[ ] Attean::API::CacheableModel
[ ] Attean::API::CacheableQuadStore
[ ] Attean::API::CacheableTripleStore
[ ] Attean::API::DirectedAcyclicGraph
[ ] Attean::API::IntersectionScopeVariables
[x] Attean::API::IRI
[x] Attean::API::Literal
[ ] Attean::API::MixedStatementIterator
[x] Attean::API::MutableModel
[ ] Attean::API::MutableQuadStore
[x] Attean::API::MutableTripleStore
[ ] Attean::API::NaryExpression
[ ] Attean::API::NaryPropertyPath
[ ] Attean::API::NullaryQueryTree
[ ] Attean::API::NumericLiteral
[ ] Attean::API::PropertyPath
[x] Attean::API::Quad
[ ] Attean::API::QuadIterator
[ ] Attean::API::QuadPattern
[ ] Attean::API::QuadStore
[ ] Attean::API::QueryTree
[x] Attean::API::RepeatableIterator
[x] Attean::API::Result
[ ] Attean::API::ResultIterator
[ ] Attean::API::TermOrVariable
[x] Attean::API::Triple
[ ] Attean::API::TripleIterator
[ ] Attean::API::TripleOrQuad
[ ] Attean::API::TripleOrQuadPattern
[ ] Attean::API::TriplePattern
[ ] Attean::API::TripleStore
[ ] Attean::API::UnaryExpression
[ ] Attean::API::UnaryPropertyPath
[ ] Attean::API::UnaryQueryTree
[ ] Attean::API::UnionScopeVariables
[ ] Attean::API::Variable
[ ] Attean::API::CanonicalizingBindingIterator
[ ] Attean::API::CanonicalizingBindingSet
[ ] Attean::API::CanonicalizingLiteral
[ ] Attean::API::CostPlanner
[ ] Attean::API::DateTimeLiteral
[ ] Attean::API::ETagCacheableModel
[ ] Attean::API::ETagCacheableQuadStore
[ ] Attean::API::ETagCacheableTripleStore
[ ] Attean::API::Plan
[ ] Attean::API::Plan::Join
[ ] Attean::API::Planner
[ ] Attean::API::ResultOrTerm
[ ] Attean::API::ResultOrTermIterator
[ ] Attean::API::ResultOrTermParser
[ ] Attean::API::TermIterator
[ ] Attean::API::TimeCacheableModel
[ ] Attean::API::TimeCacheableQuadStore
[ ] Attean::API::TimeCacheableTripleStore

Algebra

[ ] Attean::Algebra::AlternativePath
[ ] Attean::Algebra::Ask
[ ] Attean::Algebra::BGP
[ ] Attean::Algebra::Comparator
[ ] Attean::Algebra::Construct
[ ] Attean::Algebra::Distinct
[ ] Attean::Algebra::Extend
[ ] Attean::Algebra::Filter
[ ] Attean::Algebra::Graph
[ ] Attean::Algebra::Group
[ ] Attean::Algebra::InversePath
[ ] Attean::Algebra::Join
[ ] Attean::Algebra::LeftJoin
[ ] Attean::Algebra::Minus
[ ] Attean::Algebra::NegatedPropertySet
[ ] Attean::Algebra::OneOrMorePath
[ ] Attean::Algebra::OrderBy
[ ] Attean::Algebra::Path
[ ] Attean::Algebra::PredicatePath
[ ] Attean::Algebra::Project
[ ] Attean::Algebra::Reduced
[ ] Attean::Algebra::SequencePath
[ ] Attean::Algebra::Service
[ ] Attean::Algebra::Slice
[ ] Attean::Algebra::Table
[ ] Attean::Algebra::Union
[ ] Attean::Algebra::ZeroOrMorePath
[ ] Attean::Algebra::ZeroOrOnePath

Expressions

[ ] Attean::BinaryExpression
[ ] Attean::CastExpression
[ ] Attean::ExistsExpression
[ ] Attean::FunctionExpression
[ ] Attean::UnaryExpression
[ ] Attean::ValueExpression
[x] Attean::AggregateExpression

Terms, Variables, Patterns, and Bindings

[ ] Attean::Blank
[ ] Attean::IRI
[ ] Attean::Literal
[ ] Attean::Variable
[ ] Attean::Quad
[ ] Attean::QuadPattern
[ ] Attean::Triple
[ ] Attean::TriplePattern
[ ] Attean::Result

Iterators

[ ] Attean::CodeIterator
[ ] Attean::IteratorSequence
[ ] Attean::ListIterator

Stores and Models

[ ] Attean::MutableQuadModel
[ ] Attean::QuadModel
[ ] Attean::TripleModel
[ ] AtteanX::Store::Memory
[ ] AtteanX::Store::Simple

Parsers

[ ] AtteanX::Parser::NQuads
[ ] AtteanX::Parser::NTriples
[ ] AtteanX::Parser::NTuples
[ ] AtteanX::Parser::RDFXML
[ ] AtteanX::Parser::RDFXML::SAXHandler
[ ] AtteanX::Parser::SPARQLJSON
[ ] AtteanX::Parser::SPARQLTSV
[ ] AtteanX::Parser::SPARQLXML
[ ] AtteanX::Parser::SPARQLXML::SAXHandler
[ ] AtteanX::Parser::Turtle
[ ] AtteanX::Parser::Turtle::Constants
[ ] AtteanX::Parser::Turtle::Lexer
[ ] AtteanX::Parser::Turtle::Token

Serializers

[ ] AtteanX::Serializer::NQuads
[ ] AtteanX::Serializer::NTriples
[ ] AtteanX::Serializer::NTuples
[ ] AtteanX::Serializer::SPARQLCSV
[ ] AtteanX::Serializer::SPARQLTSV
[ ] AtteanX::Serializer::SPARQLXML
[ ] AtteanX::Serializer::CanonicalNTriples

Query Planning and Evaluation

[ ] Attean::IDPQueryPlanner
[ ] Attean::Plan::EBVFilter
[ ] Attean::Plan::Exists
[ ] Attean::Plan::Extend
[ ] Attean::Plan::HashDistinct
[ ] Attean::Plan::HashJoin
[ ] Attean::Plan::HeapSort
[ ] Attean::Plan::Merge
[ ] Attean::Plan::NestedLoopJoin
[ ] Attean::Plan::OrderBy
[ ] Attean::Plan::Project
[ ] Attean::Plan::Quad
[ ] Attean::Plan::Service
[ ] Attean::Plan::Slice
[ ] Attean::Plan::Table
[ ] Attean::Plan::Union
[ ] Attean::Plan::Unique
[ ] Attean::SimpleQueryEvaluator
[ ] Attean::SimpleQueryEvaluator::ExpressionEvaluator

Miscellaneous

[ ] Attean::BindingEqualityTest
[ ] Attean::Mapper
[ ] Attean::TermMap
[ ] Attean::TreeRewriter
[ ] AtteanX::RDFQueryTranslator

kjetilk commented 9 years ago

I have also made an issue #31 that is somewhat relevant to this.

kasei / attean

Add documentation for roles and classes #24