search

syavorsky / comment-parser

Generic JSDoc-like comment parser.
MIT License
239 stars 24 forks source link

Added support for custom parser markers #145

Closed alexgrozav closed 2 years ago

alexgrozav commented 2 years ago

I know this is out of the blue, but I think this would be an awesome addition to the comment-parser package.

The problem

The comment-parser package currently supports only JSDoc style comments, but it is capable of being language agnostic.

The need for this appeared after I started using sassdoc, that relies on the following format:

////
/// This is a block description
/// @param value
////

Since it is supposed to support just about any xdoc markup, I thought that extending the functionality to provide the comment markers via options would make a huge difference.

The solution

syavorsky commented 2 years ago

Great addition indeed!

One thing I want to bring up but would be open to debate about. Overall, with all arguments conveniently made optional this change seems to be backward compatible. The only breaking change is export enum Markers touch, despite I agree it makes sense semantically. It was not meant to be used as a part of external API, but it was exported and potentially is referenced in someone's code.

Maybe, to be extra cautious this may look like the following

/** @deprecated */
export enum Markers { ... }

export interface BlockMarkers {
  start: string;
  nostart: string;
  delim: string;
  end: string;
}
alexgrozav commented 2 years ago

Great addition indeed!

One thing I want to bring up but would be open to debate about. Overall, with all arguments conveniently made optional this change seems to be backward compatible. The only breaking change is export enum Markers touch, despite I agree it makes sense semantically. It was not meant to be used as a part of external API, but it was exported and potentially is referenced in someone's code.

Maybe, to be extra cautious this may look like the following

/** @deprecated */
export enum Markers { ... }

export interface BlockMarkers {
  start: string;
  nostart: string;
  delim: string;
  end: string;
}

Thank you! I completely agree, it's important that this change is entirely backwards compatible with the previous version. I've updated the code to contain the changes you've suggested.

syavorsky commented 2 years ago

published comment-parser@1.3.0