@tmcw/d12
documentation rethought
Last updated a year ago by tmcw .
MIT · Original npm · Tarball · package.json
$ cnpm install @tmcw/d12 
SYNC missed versions from official npm registry.
  _ _ ____  

| / |_ \ / ` | | __) | | (| | |/ / _,|_|___|

d12 - dx spec implementation experiment

| this is an experiment that may or may not | become a successor to documentation.js. i want to build | a successor to documentation.js, because i think jsdoc's | time has passed, the documentation.js approach is | complex in certain irreducible ways, and that hosted documentation | and dynamic documentation (autocomplete-based) should be | solved.

the ideas so far are:

  • let javascript itself define hierarchy and type
  • prioritize runtime documentation access
  • simplify, simplify, simply
  • be opinionated when it helps us simplify
  • host early

deal with later:

  • documentation format. let's just get basic comments working first.

                      _______
                     | ___  o|
                     |[_-_]_ |
  ______________     |[_____]|
 |.------------.|    |[_____]|
 ||            ||    |[====o]|
 ||            ||    |[_.--_]|
 ||            ||    |[_____]|
 ||            ||    |      :|
 ||____________||    |      :|

.==.|"" ...... |.==.| :| |::| '-.________.-' |::|| :| |''| (__)-.|''||:| ""..............""______ /:::::::::::'':::\;'-.-. \ /::=========.:.-::"\ \ \--\ \ \""""""""""""""""/ \ \__) \ jgs""""""""""""""""` '========'


how it works so far:

  1. uses rollup to start with an entry point and traverse dependencies

  2. uses a transform to associate comments with objects in an exported map

  3. traverses the exported surface of the module to produce static documentation


speculative future:

  • proposal-import-meta may provide a way forward to standardize the way that this information is passed around

  • runtime access ideally relies on a runtime transformation, which is tbd


non-goals:

  • i don't think that i want to support babel anymore. it was fun for a while, but the infinite configurations weigh heavily one me, and on node_modules. i want something with near-zero configuration that can be shared by as many people as possible.

harsh requirements:

  • on the topic of building for the future, i'm building for the future. that means that 'legacy' module formats - including much-loved commonjs - are not particularly well-supported. my expectation is that you set up your modules such that they're consumable to MICROBUNDLE, with the following crucial stipulation:

    the 'source' field of package.json is a entry point into the raw source of the module, in es6 format, using only stable features and stage 4 (finalized) javascript features.

Current Tags

  • 0.0.1                                ...           latest (a year ago)

2 Versions

  • 0.0.1                                ...           a year ago
  • 0.0.1-1                                ...           a year ago
Maintainers (1)
Downloads
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 1
Dependencies (8)
Dev Dependencies (2)
Dependents (0)
None

Copyright 2014 - 2017 © taobao.org |