nsf

Clone Tools
  • last updated 8 hours ago
Constraints
Constraints: committers
 
Constraints: files
Constraints: dates
Merge branch 'nx-doc' into 2.0.0-develop

- I created a first draft of the nx language manual, based on the new next::doc facilities. It is still incomplete, but demonstrates the use of next::doc for authoring code documentation.

To re-create the language reference (which is not yet integrated into

the build environment), run:

./nextsh tests/doc.xotcl

You will then find an output directory "NextLanguageCore" in your

/tmp/ directory.

- The next::doc comments which are sourced for generating the manual

can be found in generic/gentclAPI.decls and

generic/predefined.xotcl. I tried to add most comments to the

former, as the complexity of the predefined script does not comfort

documentation comments (and vice versa).

- Applied many fixes to the templates (based on the needs of the

language reference)

    • -7
    • +11
    /library/lib/doc-assets/command.html.tmpl
    • -3
    • +3
    /library/lib/doc-assets/object.html.tmpl
    • -1
    • +1
    /library/lib/doc-assets/package.html.tmpl
- migration guide overhaul

- define ensemble-like command for accessing instance variables ::nx::var set ... ::nx::var import ... ::nx::var exists ...

Adding the interim logo

    • binary
    /library/lib/doc-assets/nx.png
- Added a placeholder logo image, to replace the YUI one for the time being - Provided for giving some version information at either the project or package level

    • -1
    • +7
    /library/lib/doc-assets/entity.html.tmpl
- Fixed search box and autocompletion support (for packages and objects) - I allow for selecting/deselecting structural features set "private" ("deprecated" remains to be done) - I added the generation of links between documentation entities based on {{...}} markers. Any marker (code as well as links) can now be used in both description and parts sections.

- Fixed search box and autocompletion support (for packages and objects) - I allow for selecting/deselecting structural features set "private" ("deprecated" remains to be done) - I added the generation of links between documentation entities based on {{...}} markers. Any marker (code as well as links) can now be used in both description and parts sections.

    • -3
    • +3
    /library/lib/doc-assets/entity.html.tmpl
    • -3
    • +9
    /library/lib/doc-assets/object.html.tmpl
- Adding basic support for subcommands (a @subcommand part type; formerly @variant) - Introducing comment reuse and cross-linkage along the class hierarchy upwards ("subclass of ...", showing inherited attributes and methods; using a @superclass attribute) - Amending the documentation of @param and @return with "type" information (checkoptions, constraints, defaults) - Showing both per-class and per-object methods - I now allow for inline- and out-of-line (block) code snippets in the description sections, based on wiki-like {{{...}}} marker annotation (same as in scaladoc2). - Adding support for newline representations in description sections (for a more convenient formatting). - Some bugfixes (e.g., @object-method did not work outside of an initcmd) - Started refactoring the entity tracing procedure (moving from [namespace import] resolution to mixin-based creation tracing)

    • -4
    • +47
    /library/lib/doc-assets/command.html.tmpl
    • -8
    • +140
    /library/lib/doc-assets/object.html.tmpl
- Adding basic support for subcommands (a @subcommand part type; formerly @variant) - Introducing comment reuse and cross-linkage along the class hierarchy upwards ("subclass of ...", showing inherited attributes and methods; using a @superclass attribute) - Amending the documentation of @param and @return with "type" information (checkoptions, constraints, defaults) - Showing both per-class and per-object methods - I now allow for inline- and out-of-line (block) code snippets in the description sections, based on wiki-like {{{...}}} marker annotation (same as in scaladoc2). - Adding support for newline representations in description sections (for a more convenient formatting). - Some bugfixes (e.g., @object-method did not work outside of an initcmd) - Started refactoring the entity tracing procedure (moving from [namespace import] resolution to mixin-based creation tracing)

    • -4
    • +47
    /library/lib/doc-assets/command.html.tmpl
    • -8
    • +140
    /library/lib/doc-assets/object.html.tmpl
- added to git

- don't allow names with namespace separators or colon prefix in importvar/instvar - provide error message, when method (proc scope) is not found - fix array boundaries for looping on variables in importvar/instvar - extended regression test

- provide spacing in conditional assignments

- fix cleanup of subclasses of metaclasses, keeping metaclass property (thanks to Stefan for digging into this)

- Added a first set of documentation templates, based on the the TemplateData engine and the YUI doc styles available from http://yuilibrary.com/downloads/ (see library/lib/doc-assets/*.tmpl.html) - Added a @project entity class, which will become the root concept in a documentation hierarchy. For now, it only serves for some auxiliary purposes when processing the doc templates. - Continued documenting the next::doc package for testing purposes.

    • -0
    • +162
    /library/lib/doc-assets/ac-js
    • -0
    • +42
    /library/lib/doc-assets/api-js
    • -0
    • +242
    /library/lib/doc-assets/api.css
    • binary
    /library/lib/doc-assets/bg_hd.gif
    • -0
    • +44
    /library/lib/doc-assets/command.html.tmpl
    • -0
    • +116
    /library/lib/doc-assets/entity.html.tmpl
    • -0
    • +111
    /library/lib/doc-assets/object.html.tmpl
    • -0
    • +56
    /library/lib/doc-assets/package.html.tmpl
    • -0
    • +7
    /library/lib/doc-assets/reset-fonts-grids-min.css
    • -0
    • +7
    /library/lib/doc-assets/source.html.tmpl
    • binary
    /library/lib/doc-assets/yui.png
- I made sure that the existing HtmlRenderer infrastructure remains functional - Added a simplistic templating machinery (see TemplateData), based on cascading [subst] calls in per-object evals (assuming the nonleaf mode) and a basic templating instruction set (i.e., "let", "for", as well as "?" representing if-elseif-else blocks and "include" for composing template fragments). This will help me to transpose the YUI doc templates more easily (and split them up into template fragments). Also, it will allow future documentation writers to provide custom templates or modifications of existing ones. This was somehow inspired by Kristoffer Lawson "templating engine" in his Spindle web framework, which is solely based on Tcl namespaces, however.

- Removed @attribute parts and realise them as @param parts which are parts of @object parts - Renamed PartAttribute->get_part() to require_part() - The line scanner now stores all comment lines as list by using [split] at an early stage to improve the robustness when line strings are fed to list-specific commands.

- Introduced a PartClass meta-class which seconds Part and its subclasses (for a uniform id generation etc.) - Removed the kludge around new_from_attribute(), there is now a canonical new(). - "scope" turned into a property of PartAttributes and, as such, of the association (slot) objects managing parts. this more closely resembles the idea of per-class and per-object interfaces. in turn, parts now contain a navigatable association to their managing part attributes (e.g., to resolve their scope). - Adding some basic exception-catching infrastructure too better differentiate between error conditions (style violation, invalid tags, arbitrary errors emerging from the parsing machinery). Adjusting and extending the test suite. - Simplified/generalised the parser's tag dispatcher; also, there is no a general @doc tag which allows to add documentation lines as tagged parts, rather than a distinct doc block - Removed the tagged_entity mechanisms and per-tag forwards on EntityClass - Documentation blocks may now contain intermediate space lines (by adding a space->text transition to the parsing spec). - Adding basic support to trace script sources from [package req] calls, needs to be polished and refactored

    • -163
    • +305
    /library/lib/doc-tools.xotcl
- provide explicit error message stating the "substdefault" is not allowed for setters - don't add "substdefault" a second time, in case it was already used - never add "substdefault" to methodopts - extended regression test

- Renamed EntityFactory to EntityClass - Introduced PartAttribute for managing entity-part associations, they also protect against duplicate entries - Added NextAttribute (though it should fuse with parameter entities in the end) - Completed basic support for embedded (initcmd) and freestanding (script): This multi-stage processing introduces a precedence order between the commenting levels (script < initcmd < method bodies). - Renamed most entity classes using their tag equivalent (@object, ...) - Introduced offset feature for the comment line scanner (offsets are used to select embedded comment blocks, e.g., in initcmds or method bodies) - Parsing of arbitrary scripts is now realised in a child interp - Introduced qualified entity names (e.g., @attribute Bar#a1) and per-object scope (through a scope prefix in tags, e.g., @object-method) - Did some cleanup and extended the test suite

    • -391
    • +505
    /library/lib/doc-tools.xotcl
- minor updates

- fix wording in documentation

- update migration guide from XOTcl 2 to Next

- fix wording in documentation

Finished and tested the rewrite of the scanning&parsing front-end for the doc processor. Remains to be integrated with the intermediate @ notation (basics are already working)

    • -179
    • +258
    /library/lib/doc-tools.xotcl
Upgrading to the ::nx::* namespace renaming

Merge branch 'next-doc' into nx-doc

tests/doc.xotcl

    • -129
    • +480
    /library/lib/doc-tools.xotcl
- changed prefix from "::next::" to "::nx"

    • -46
    • +46
    /library/serialize/Serializer.xotcl
  1. … 7 more files in changeset.
- updated Changelog - added Annouce files