spec files

[jonschlinkert]

What if we created YAML "spec" files for all of the filters (one file for each category of filters) like array-spec.yaml, with something like the following:

category: array
methods:
  - name: pad_end
    description: "Pads the given string with another string until the resulting string reaches the specified maximum length. The padding is applied from the end (right) of the current string."
    examples: 
      - title: Example
        signature: "string.pad_end(str, maxLength[, padString])"
        args: ['Foo', 10, '0']
        expected: 'Foo0000000'
    tests:
      - it: "Should append '0' to the string"
        args: ['Foo', 10, '0']
        expected: 'Foo0000000'

Then we just run a command in the terminal to generate the tests and docs and see which methods still need to be covered.

This might seem like over-engineering, but I'd be able to use parts of this on many projects, so I'm thinking it would be worth it.

On this topic, I've been working on a new documentation system (that I'll be pushing up soon) that can do the following (and more):

• lint code comments for typos/English grammatical errors
• lint examples in code comments for code errors
• lint code examples for formatting, missing params, descriptions, examples, etc.
• generate markdown documentation from code comments
• fill in missing information with data from the repository (package.json, .git/config, etc.)
• lint markdown docs for "documentation coverage"
• cross-reference code comments with unit tests, spec files, and documentation examples, and returns a report with undocumented methods, code coverage, etc.
• use plugins to add other features

Thoughts? @doowb @tunnckoCore?

(P.S. @tunnckoCore I saw Docks, it looks nice. However, I've been working on (and thinking about) this "new" documentation system for a couple of years, and it's very different than Docks. I'd be happy to add you as a collaborator when I push it up)

[tunnckoCore]

Yup sounds it worth it.

As about the documentation system, yea exactly... I was thinking about the same thing too (the eslint and prettier on the code comment examples). Why not work on Docks together? I don't see how it's "very different". As you can see it has a few built-in plugins, plus rendering one (which isn't great currently but works pretty well - see parse-commit-message for bigger api docs generated with it). When I switch to the latest parse-comments most of the plugins will disappear. All plugins are running for each code comment.

I'll add examples linting in Docks anyway... Currently, it works very well and better than Verb for what I need, that's why I'm using it instead of Verb

[jonschlinkert]

Oh, I assumed Docks was different enough that you thought it was worth creating a separate lib instead of contributing to Verb and the other comment parsing/documentation libs I created ;)

…

Sent from my iPhone

On Nov 25, 2018, at 10:48 PM, Charlike Mike Reagent ***@***.***> wrote: Yup sounds it worth it. As about the documentation system, yea exactly... I was thinking about the same thing too (the eslint and prettier on the code comment examples). Why not work on Docks together? I don't see how it's "very different". As you can see it has a few built-in plugins, plus rendering one (which isn't great currently but works pretty well - see parse-commit-message for bigger api docs generated with it). When I switch to the latest parse-comments most of the plugins will disappear. All plugins are running for each code comment. I'll add examples linting in Docks anyway... Currently, it works very well and better than Verb for what I need, that's why I'm using it instead of Verb — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[jonschlinkert]

And I don’t mind that everyone keeps taking the ideas from Verb and creating other documentation systems. eventually we’ll all end up with a system we like. Ours or theirs.

…

Sent from my iPhone

On Nov 25, 2018, at 10:48 PM, Charlike Mike Reagent ***@***.***> wrote: Yup sounds it worth it. As about the documentation system, yea exactly... I was thinking about the same thing too (the eslint and prettier on the code comment examples). Why not work on Docks together? I don't see how it's "very different". As you can see it has a few built-in plugins, plus rendering one (which isn't great currently but works pretty well - see parse-commit-message for bigger api docs generated with it). When I switch to the latest parse-comments most of the plugins will disappear. All plugins are running for each code comment. I'll add examples linting in Docks anyway... Currently, it works very well and better than Verb for what I need, that's why I'm using it instead of Verb — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or mute the thread.

[tunnckoCore]

Oh, don't take it wrong. I would, but it was just a lot more faster to write 100 lines of code to make such a thing, instead of losing myself in contributing to a few dependencies of Verb or other helpers. I was thinking about the name "Docks" for years anyway (published it back in ~2016) and even in 2018 I still don't like to have deps. Lately trying to drop as many devDeps as possible to narrow it down to only test runner.