Closed murolem closed 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.
@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!
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
...
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?
Yeah, it's works now, documentation is being generated, but there are new issues:
utils
, why is that?@returns
in my case.Should I close this issue since it is resolved?
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 😅
Uh oh, okay. Thanks anyway.
Thanks to you for the bug report, I'm sorry for the misunderstanding
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:
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)
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.
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
@category
@example
@since
@deprecated
e)
:+1:
@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!
docs-ts
is unable to locate the config despite it being in the root directory of my project. I just want to setenforceVersion
tofalse
and live happily ever after. Mydocs-ts.json
:CLI output on
npx docs-ts
: