bencoveney / barrelsby

Is your feature request related to a problem? Please describe.

I note the issue that requested the jsdoc header was implemented here #77 (comment)

However, when using eslint-plugin-tsdoc having this header breaks build steps that call the linter.

Describe the solution you'd like

A config option to either disable or modify the header comment.

Describe alternatives you've considered

Disabling eslint rule on **/index.ts files, but would prefer not to do this if possible.
Monkey patching the library with patch-package, however this doesn't seem like a great idea lol.

Suggested shape

barrelsby/src/tasks/BuildBarrel.ts

Line 71 in 270a5f7

const contentWithHeader = addHeaderPrefix(content);

export type Prefix = string | boolean | undefined

export interface BarrelsbyOptions {
  directory: Directory
  barrelType: StructureOption
  quoteCharacter: QuoteCharacter
  semicolonCharacter: SemicolonCharacter
  barrelName: string
  logger: Logger
  baseUrl: BaseUrl
  exportDefault: boolean
  local: boolean
  include: string[]
  exclude: string[]
  prefix: Prefix
}

const contentWithHeader = addHeaderPrefix(content, prefix);

barrelsby/src/builders/header.ts

Line 1 in f29f014

export function addHeaderPrefix(content: string): string {

export function addHeaderPrefix(content: string, prefix: Prefix): string {
  if (prefix === false) {
    return content
  }

  return `/**
 * ${prefix ?? "@file Automatically generated by barrelsby."}
 */
${content}`
}

@BitForger @bencoveney If this is something you'd accept a PR on I can do one up if you like?

Hi @prescience-data

Some bits of context:

Part of the previous rationale for adding the header was that it might be useful to have something identifable in the barrel files. The idea was that if/when barrelsby deletes files, we could have something to look for within the file before deleting, to prevent barrelsby accidentally deleting files that aren't barrels. You might've seen clues to that here #77 (comment) but I figure it's worth having it noted here in this issue 👍 I don't think we implemented that check yet - however if we were to do it in the future then it could be useful to still have the string Automatically generated by barrelsby. somewhere in the file.

I'm not sure exactly what problem eslint-plugin-tsdoc has with the comments - but I'll just note that the @file tag is valid for JSDoc (https://jsdoc.app/tags-file.html). Do you have an error log or some more details about why eslint-plugin-tsdoc is unhappy? I assume its the @file tage but perhaps its the comment format instead?

Finally, your proposed option changes maybe allow for this, but I figure I should mention that: it will be better to avoid changing any generated output for users with default options - any options that would change the output should be opt-in. This is so we can avoid creating surprise file changes for anyone who updates the packages and then re-runs the build.

With all that said - I can think of two options for solving the problem:

Option A

What you've proposed, but:

Any existing output remains the same unless users opt-in to the feature.
In any documentation for the new option, we suggest/recommend to users that they should include Automatically generated by barrelsby. in their output.

Option B

A --simple-header or --simple-prefix option (name can be bike-shedded 😄) that would make the generated comments simpler - so that they don't conflict with any tooling - like:

// Automatically generated by barrelsby.

I'd be open to either one of these solutions - interested to see about @BitForger 's thoughts too though 👍

As of 2.5.0 you can disable the header completely.

I see this is because of the TSDoc project which is entirely different than JSDoc. The project itself is in the 0.x release phase and I don't see a huge reason to make changes around it considering it hasn't made it to 1.x after 4 years.
JSDoc still appears to be the standard for now so this is a nice to have change.

Ah yes I just noticed this - thanks so much for that!

Allow customisation of header comment