Index: library/lib/doc-tools.xotcl
===================================================================
diff -u -r3a4738021c1af0c9c1809b9932506cf2031505f4 -r2c61de6701476bd46fe133a28742810c14e411ac
--- library/lib/doc-tools.xotcl (.../doc-tools.xotcl) (revision 3a4738021c1af0c9c1809b9932506cf2031505f4)
+++ library/lib/doc-tools.xotcl (.../doc-tools.xotcl) (revision 2c61de6701476bd46fe133a28742810c14e411ac)
@@ -272,7 +272,9 @@
#
:method text {} {
# TODO: Provide \n replacements for empty lines
- subst [join ${:@doc} " "]
+ if {[info exists :@doc]} {
+ subst [join ${:@doc} " "]
+ }
}
}
@@ -394,13 +396,16 @@
set :part_class @param
}
:method signature {} {
+ #
+ # TODO: What was the original intention of introducing arguments?!
+ #
if {[info exists :arguments]} {
set arguments ${:arguments}
} else {
set arguments [list]
- foreach p [:params] {lappend arguments [$p param]}
+ foreach p [:@param] {lappend arguments [$p name]}
}
- set result "obj ${:name} $arguments"
+ set result "method ${:name} $arguments"
}
:method process {
{-initial_section:optional "context"}
@@ -450,6 +455,68 @@
namespace eval ::nx::doc {
+
+ Class create TemplateData {
+ :method render {template {entity:substdefault "[self]"}} {
+ #
+ # Here, we assume the -nonleaf mode being
+ # active for [eval].
+ #
+ $entity eval [list subst $template]
+ }
+
+
+ #
+ # some instructions for a dwarfish, embedded templating language
+ #
+ :method let {var value} {
+ uplevel 1 [list ::set $var [expr {[info exists value]?$value:""}]]
+ return
+ }
+ :method for {var list body} {
+ set rendered ""
+ ::foreach $var $list {
+ uplevel 1 [list ::set $var [set $var]]
+ append rendered [uplevel 1 [list subst $body]]
+ }
+ return $rendered
+ }
+ :method ?var {varname args} {
+ uplevel 1 [list :? -ops [list [::nx::core::current proc] -] \
+ "\[info exists $varname\]" {*}$args]
+ }
+ :method ? {
+ {-ops {? -}}
+ expr
+ then
+ next:optional
+ args
+ } {
+ if {[info exists next] && $next ni $ops} {
+ return -code error "Invalid control operator '$next', we expect one of $ops"
+ }
+ set condition [list expr $expr]
+ if {[uplevel 1 $condition]} {
+ return [uplevel 1 [list subst $then]]
+ } elseif {[info exists next]} {
+ if {$next eq "-"} {
+ set args [lassign $args next_then]
+ if {$next_then eq ""} {
+ return -code error "A then script is missing for '-'"
+ }
+ if {$args ne ""} {
+ return -code error "Too many arguments: $args"
+ }
+ return [uplevel 1 [list subst $next_then]]
+ }
+ return [:$next {*}$args]
+ }
+ }
+
+ :method include {template} {
+ uplevel 1 [list subst $template]
+ }
+ }
#
# Provide a simple HTML renderer. For now, we make our life simple
@@ -458,25 +525,44 @@
# We could think about a java-doc style renderer...
#
- Class create HTMLrenderer {
+ Class create Renderer {
+ :method render {} {
+ :render=[namespace tail [:info class]]
+ }
+ }
+
+ Class create HtmlRenderer -superclass Renderer {
# render command pieces in the text
- :method cmd {text} {return <@TT>$text@TT>}
+ :method tt {text} {return <@TT>$text@TT>}
- #
- # render xotcl commands
- #
- :method renderCmd {} {
- puts "
[:cmd ${:name}]
\n[:text]"
- set variants [sorted [:variants] name]
- if {$variants ne ""} {
+
+ :method render=@package {} {
+ puts "[:tt ${:name}]
\n[:text]"
+ set req [:@require]
+ if {$req ne ""} {
puts " "
- foreach v $variants {puts " - [$v text]"}
+ foreach r $req {puts "
- $r
"}
puts "
"
}
- set params [:params]
+ puts "\n"
+
+ }
+
+ #
+ # render xotcl commands
+ #
+ :method render=@command {} {
+ puts "[:tt ${:name}]
\n[:text]"
+ # set variants [sorted [:variants] name]
+ # if {$variants ne ""} {
+ # puts " "
+ # foreach v $variants {puts " - [$v text]"}
+ # puts "
"
+ # }
+ set params [:@param]
if {$params ne ""} {
puts " "
- foreach v $params {puts " - [$v cmd [$v name]] [$v text]"}
+ foreach v $params {puts "
- [$v tt [$v name]] [$v text]"}
puts "
"
}
puts "\n"
@@ -485,33 +571,40 @@
#
# render next classes
#
- :method renderClass {} {
- puts "[:cmd ${:name}]
\n[:text]"
- set methods [sorted [:methods] name]
- if {$methods ne ""} {
- puts "
Methods of ${:name}:\n "
- foreach v $methods {if {[$v scope] eq "class"} {$v renderMethod}}
- puts "
"
- puts "
Object Methods of ${:name}:\n "
- foreach v $methods {if {[$v scope] eq "object"} {$v renderMethod}}
- puts "
"
+ :method render=@object {} {
+ puts "[:tt ${:name}]
\n[:text]"
+ if {[info exists :@method]} {
+ set methods [sorted [:@method] name]
+ if {$methods ne ""} {
+ puts "
Methods of ${:name}:\n "
+ foreach m $methods {$v render}
+ puts "
"
+ }
}
+ if {[info exists :@object-method]} {
+ set methods [sorted [:@object-method] name]
+ if {$methods ne ""} {
+ puts "
Object methods of ${:name}:\n "
+ foreach m $methods {$v render}
+ puts "
"
+ }
+ }
puts "\n"
}
#
# render next methods
#
- :method renderMethod {} {
- puts "[:cmd [:signature]]
\n[:text]"
- set params [:params]
+ :method render=@method {} {
+ puts "[:tt [:signature]]
\n[:text]"
+ set params [:@param]
if {$params ne ""} {
puts " "
- foreach v $params {puts " - [$v cmd [$v name]] [$v text]"}
+ foreach v $params {puts "
- [$v tt [$v name]] [$v text]"}
puts "
"
}
if {${:returns} ne ""} {
- puts " Returns: ${:returns}"
+ puts " Returns: ${:@return}"
}
puts "\n"
}
@@ -755,21 +848,27 @@
}
}
- :method doc {{-renderer ::nx::doc::HTMLrenderer}} {
+ :method doc {{-renderer ::nx::doc::HtmlRenderer}} {
# register the HTML renderer for all docEntities.
Entity mixin add $renderer
+
+ puts "Tcl packages
\n"
+ foreach pkg [sorted [@package info instances] name] {
+ $pkg render
+ }
+
- puts "Primitive XOTcl framework commands
\n"
+ puts "Primitive Next framework commands
\n"
foreach cmd [sorted [@command info instances] name] {
- $cmd renderCmd
+ $cmd render
}
puts "
\n\n"
- puts "XOTcl Classes
\n"
+ puts "Next objects
\n"
foreach cmd [sorted [@object info instances] name] {
- $cmd renderClass
+ $cmd render
}
puts "
\n\n"
Index: tests/doc.xotcl
===================================================================
diff -u -r3a4738021c1af0c9c1809b9932506cf2031505f4 -r2c61de6701476bd46fe133a28742810c14e411ac
--- tests/doc.xotcl (.../doc.xotcl) (revision 3a4738021c1af0c9c1809b9932506cf2031505f4)
+++ tests/doc.xotcl (.../doc.xotcl) (revision 2c61de6701476bd46fe133a28742810c14e411ac)
@@ -514,6 +514,7 @@
? [list $i eval [list ::nx::core::is [@package id next::doc] object]] 1
puts stderr [$i eval [list [@package id next::doc] text]]
puts stderr [$i eval [list [@package id next::doc] @require]]
+ $i eval [list ::nx::doc::make doc]
interp delete $i
}