"Missing examples" when examples are enforced in fp-ts-std

[samhh]

Repro:

1. Clone fp-ts-std (and checkout 5870c44).

2. Add a docs-ts.json file with the following contents:

3. {
   "enforceExamples": true
   }

4. Run yarn docs (alias for docs-ts).

5. The output will be as follows:

14/03/2021 | 17:39:39 | DEBUG | Project name detected: fp-ts-std
14/03/2021 | 17:39:39 | DEBUG | Checking for configuration file...
14/03/2021 | 17:39:39 | INFO | Found configuration file
14/03/2021 | 17:39:39 | DEBUG | Parsing configuration file found at: /home/sam/dev/fp-ts-std/docs-ts.json
14/03/2021 | 17:39:39 | INFO | Found 17 modules
14/03/2021 | 17:39:39 | DEBUG | Parsing files...
Missing examples in src/Array.ts#Array documentation
Missing examples in src/Boolean.ts#Boolean documentation
Missing examples in src/Date.ts#Date documentation
Missing examples in src/Debug.ts#Debug documentation
Missing examples in src/Either.ts#Either documentation
Missing examples in src/Env.ts#Env documentation
Missing examples in src/Function.ts#Function documentation
Missing examples in src/index.ts#index documentation
Missing examples in src/IO.ts#IO documentation
Missing examples in src/JSON.ts#JSON documentation
Missing examples in src/Number.ts#Number documentation
Missing examples in src/Option.ts#Option documentation
Missing examples in src/Record.ts#Record documentation
Missing examples in src/String.ts#String documentation
Missing examples in src/Task.ts#Task documentation
Missing examples in src/URL.ts#URL documentation
Missing examples in src/URLSearchParams.ts#URLSearchParams documentation
error Command failed with exit code 1.

I have examples for I think absolutely everything, and they do successfully make it into the generated documentation.

Small modules which could be easier to verify would be Debug, IO, and Task.

[gcanti]

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)

[samhh]

Hmm, I hadn't even considered that. Is that desirable behaviour?

[IMax153]

@gcanti is correct - the parser is detecting missing documentation at the module level. See here: https://github.com/gcanti/docs-ts/blob/19ca164740a48f6cc2f9557c823e2ab05c9450e9/src/Parser.ts#L755-L759

As a side note, we decided to go this route based on the discussion in #23.

More than happy to discuss further.

[samhh]

Gotcha. I've two pieces of feedback then depending on where we want to go with it:

1. 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.
2. If this won't be actioned in terms of configuration options, could the parser error be improved? It's extremely vague.

[IMax153]

@gcanti, @gillchristian, @thought2 - do you guys have any opinion on how to solve this issue?

[gcanti]

I agree with point 1. (not a desirable behaviour for examples)

[gillchristian]

Agree, we should not enforce examples on module level docs.

I can work on this tonight. Unless somebody wants to give it a shot.

[m-bock]

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'])

[IMax153]

@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.

[gillchristian]

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 😬