Cannot create a config. about docs-ts HOT 11 CLOSED

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 😅

from docs-ts.

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

from docs-ts.

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

from docs-ts.

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

from docs-ts.

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?

from docs-ts.

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

• The TOC root entry is called utils, why is that?
• The documentation on overloaded methods is partially ignored - all overloads are showing up, but documentation is there only on the first one of the overloads.
• At least one of the JSDoc's tags is just ignored, @returns in my case.

Should I close this issue since it is resolved?

from docs-ts.

Uh oh, okay. Thanks anyway.

from docs-ts.

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

from docs-ts.

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.

from docs-ts.

I believe we could correct that by modifying parseModuleDocumentation

👍

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)

👍 the supported tags are

• @category
• @example
• @since
• @deprecated

e)

👍

from docs-ts.

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

from docs-ts.