gcanti / docs-ts

A zero-config documentation tool for my TypeScript projects
https://gcanti.github.io/docs-ts/
MIT License
101 stars 17 forks source link

Cannot create a config. #23

Closed murolem closed 3 years ago

murolem commented 3 years ago

docs-ts is unable to locate the config despite it being in the root directory of my project. I just want to set enforceVersion to false and live happily ever after. My docs-ts.json:

{
    "enforceVersion": false
}

CLI output on npx docs-ts:

...
1 modules found
Parsing files...
missing documentation in src/index.ts module
missing @since tag in src/index.ts#foo documentation
missing @since tag in src/index.ts#bar documentation
...
gcanti commented 3 years ago

@Eleseer I merged v0.6 a couple of hours ago, it's not yet "officially" released (I'm testing right now the new version against my projects).

You can run npm i docs-ts@next to get the experimental release though.

murolem commented 3 years ago

@Eleseer I merged v0.6 a couple of hours ago, it's not yet "officially" released (I'm testing right now the new version against my projects).

You can run npm i docs-ts@next to get the experimental release though.

I'll try it tomorrow then, ty!

murolem commented 3 years ago

I have installed the docs-ts@next and now config is readable - half the problem solved, but Missing documentation error persists:

...
14.02.2021 | 16:45:16 | DEBUG | Project name detected: @aliser/foo
14.02.2021 | 16:45:16 | DEBUG | Checking for configuration file...
14.02.2021 | 16:45:16 | INFO | Found configuration file
14.02.2021 | 16:45:16 | DEBUG | Parsing configuration file found at: ...\docs-ts.json
14.02.2021 | 16:45:16 | INFO | Found 1 modules
14.02.2021 | 16:45:16 | DEBUG | Parsing files...
Missing documentation in src/index.ts module
...
gcanti commented 3 years ago

Thanks @Eleseer, looks like "enforceVersion": false is not respected at the module level.

If you put a /** */ comment on the very first line of your module the error goes away I guess?

murolem commented 3 years ago

Yeah, it's works now, documentation is being generated, but there are new issues:

Should I close this issue since it is resolved?

gcanti commented 3 years ago

Should I close this issue since it is resolved?

No thanks, putting a /** */ comment is just a workaround, the issue is still unresolved.

but there are new issues

Oh... I believe there has been a misunderstanding, this is a tool built for my own use.

@IMax153 I'm afraid the new README file will lead users to think that this is a general purpose documentation tool 😅

murolem commented 3 years ago

Uh oh, okay. Thanks anyway.

gcanti commented 3 years ago

Thanks to you for the bug report, I'm sorry for the misunderstanding

IMax153 commented 3 years ago

Hmmm - @gcanti, I suppose that those of us who have been using docs-ts for our own personal projects take it for granted that we tend to structure our projects/documentation in the same way that you do. Therefore, I can completely understand how the new README would be misleading.

@Eleseer - apologies for any confusion that this has caused! It was certainly not my intent.

As for respecting the Config at the module level, I believe we could correct that by modifying parseModuleDocumentation :

export const parseModuleDocumentation: Parser<Documentable> = pipe(
  RE.ask<ParserEnv>(),
  RE.chainEitherK(env => {
    const name = getModuleName(env.path)
    // If any of the settings enforcing documentation are set to `true`, then
    // a module should have associated documentation
    const isDocumentationRequired = M.fold(M.monoidAny)([
      env.settings.enforceDescriptions,
      env.settings.enforceExamples,
      env.settings.enforceVersion
    ])
    const onMissingDocumentation = () =>
      isDocumentationRequired
        ? E.left(`Missing documentation in ${env.path.join('/')} module`)
        : E.right(Documentable(name, O.none, O.none, false, RA.empty, O.none))
    return pipe(
      env.sourceFile.getStatements(),
      RA.foldLeft(onMissingDocumentation, statement =>
        pipe(
          statement.getLeadingCommentRanges(),
          RA.foldLeft(onMissingDocumentation, commentRange =>
            pipe(
              getCommentInfo(name)(commentRange.getText())(env),
              E.map(info =>
                Documentable(name, info.description, info.since, info.deprecated, info.examples, info.category)
              )
            )
          )
        )
      )
    )
  })
)

As for the README, I can think of two ways to tackle this issue:

  1. Make the README more detailed a). Add a statement saying that this library is primarily for your own personal use b). State that this library is opinionated about what is included in documentation (could point to fp-ts as an example?) c). Could also include a more feature-rich example of documentation d). List JSDoc tags that are respected by docs-ts e). Describe other common pain points for new users (e.g., only documentation for the first function overload will be included)

  2. Gut the README a). Add a statement saying that this library is primarily for your own personal use b). Remove most of the README content, only leaving behind the information about the new config file

What do you think? Is there a better solution? I can take care of working on whatever option is selected.

gcanti commented 3 years ago

I believe we could correct that by modifying parseModuleDocumentation

:+1:

a) b)

Yes, we could state that this is primarily used as an opinionated documentation tool for the fp-ts ecosystem

c)

we could point to fp-ts as an example

d)

:+1: the supported tags are

e)

:+1:

IMax153 commented 3 years ago

@gcanti - I split up this issue into two separate PRs since one is addressing a source code issue and one is addressing a documentation issue.

For the issues with the README, I added a disclaimer to the beginning of the document just under the table of contents outlining that this library is primarily intended for use with fp-ts ecosystem libraries. In addition, I added a table outlining the supported JSDoc tags. And finally, I added a FAQ section that I figured we could add to as questions about specific use cases arise over time.

Let me know what you think!