validator.js
validator.js copied to clipboard
validatorjs
Improve docs
Summary
As discussed at express-validator/express-validator#1009 a more schematic documentation would help third party libraries to autogenerate docs for methods.
Detailed design
validators: [
{
name: 'isAlpha(str [, locale, options])',
description: 'foo',
args: [{ name: 'locale', type: 'string' constraints: 'Is one of [it-IT,...]' }],
options: [{ name: 'ignore', type: 'string | RegExp', defaults: null }]
},
{
name: 'isAscii(str)',
args: null,
options: null
}
],
sanitizers: [
...
]
It would also help when reviewing PRs.
Happy to implement this if you think this is a good idea! /cc @profnandaa @tux-tn @ezkemboi
Can give examples of the libraries that use this kind of interface? I'm not too conversant in the space...
Pinging this, I have just analyzed an algolia report of express-validator website where most of the searches with no result are related with the docs of this repo.
Totally agree with the idea @fedeci !
I'm wondering if there is a standard or a definition for the schema design you are suggesting?
@fedeci Can using JSDoc annotations be an option?
I guess the idea is to have a solution that is:
- Easy to implement and maintain
- Straightforward for contributors
- Can be used by other libraries based on validator like
express-validator - Can be used automating documentation generation
Yes, JSdoc could be used but if I am not wrong is really limited. However with it we could for sure automate doc generation with a pre-commit hook
@fedeci how will the format you suggested work with your library? Docusaurus can handle that schema design or will you work on a custom adapter?
Docusaurus can't handle that schema design, but since it is json it would be really easy to generate docs. I've been working with tsdoc parser in the last couple weeks and it's a nightmare compared to json for these kind of things.