Comments (10)
@thought2 - That was my thought process as well. Especially for libraries that can be complex to get started with. A great example would be the port of Haskell's scalpel web scraping library that I have been working on (link for those that are interested in taking a closer look).
However, since @gcanti, @gillchristian, and @samhh feel that this is not the direction to go I am also fine with removing the top-level module requirement for documentation when enforceExamples
is set to true. Hopefully the fact that we are enforcing examples everywhere else in the code when this flag is turned on will encourage devs to put top-level examples as well 😅.
@gillchristian - since I know that the issue needs to be addressed in two places, I am already working on a PR. Should be submitting shortly.
from docs-ts.
My guess is that is detecting a missing example in the module documentation (i.e. the very first comment at the top of the module)
from docs-ts.
I agree with point 1. (not a desirable behaviour for examples)
from docs-ts.
I'm fine with either way :)
However, I find it somehow appealing to also enforce examples on the module level if this option is enabled.
It encourages you think about the module as if you've never heard of it before.
Maybe to put a selection of some representative functions that the module provides into a pipe.
For Array e.g.:
import * as A from 'fp-ts/Array'
import { pipe } from 'fp-ts/function'
const sample : Array<string> = pipe(
[1, 2, 3, 4],
A.filter((n) => n >= 2),
A.map((n) => n.toString())
)
assert.deepStrictEqual(sample, ['3', '2'])
from docs-ts.
Hmm, I hadn't even considered that. Is that desirable behaviour?
from docs-ts.
@gcanti is correct - the parser is detecting missing documentation at the module level. See here:
Lines 755 to 759 in 19ca164
As a side note, we decided to go this route based on the discussion in #23.
More than happy to discuss further.
from docs-ts.
Gotcha. I've two pieces of feedback then depending on where we want to go with it:
- I don't consider this desirable behaviour for examples specifically. What's an appropriate example for an "Array" module? I can't think of one, but I'd like to enforce examples for all exports. If deemed actionable I suppose there's a few ways to solve this though I can't think of one that's obviously ideal.
- If this won't be actioned in terms of configuration options, could the parser error be improved? It's extremely vague.
from docs-ts.
@gcanti, @gillchristian, @thought2 - do you guys have any opinion on how to solve this issue?
from docs-ts.
Agree, we should not enforce examples on module level docs.
I can work on this tonight. Unless somebody wants to give it a shot.
from docs-ts.
Another option could be to add an extra configuration to enforce module examples separately from the other examples.
Not sure if it's the road we want to go and keep populating the config tho 😬
from docs-ts.
Related Issues (20)
- [discussion] Why use ts-morph over tsc? HOT 3
- Error when compiling docs HOT 2
- `@types/node` is needed HOT 2
- Horizontal scrolling in rendered code blocks HOT 4
- @example imports still buggy HOT 1
- Incorrect return type for `toNullable` and `toUndefined` HOT 1
- View rendered docs locally HOT 4
- Omit `.ts` in sidebar HOT 2
- Can't ignore private methods from being generated HOT 1
- Enforcement exclusions HOT 4
- Modules with only exports from other modules result in empty ToC
- Feature request: Forward options to ts-morph
- ts-morph needs updating
- tsx support
- "Why" section of the readme seems incomplete HOT 1
- Consider migrating to vitepress
- Bug: getter documentation is skipped
- Document how to make use of & debug the example type checking? HOT 2
- Prettier as peer dependency prevents upgrading it in consumers projects HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs-ts.