search

cibernox / ember-cli-yuidoc

EmberCLI addon for generate documentation from YUIDoc coments
MIT License
55 stars 25 forks source link

[BUGFIX] Adds support for decorators #52

Closed pzuraq closed 5 years ago

pzuraq commented 5 years ago

This PR adds general support for decorators when used within markdown blocks. It does this by reaching into the YUIDoc global and patching the method that handles comment parsing. Given YUIDoc is pretty much abandoned at this point, this should be a relatively stable patch. Presumably, attempts to modernize it will also add decorator support, should they occur.

The fix replaces all @ symbols within codeblocks with a placeholder, processes them, and then switches them back after processing.

cibernox commented 5 years ago

LGTM.

rwjblue commented 5 years ago

@pzuraq - don’t we need to preserve the known set of YUIDoc pragma’s? Things like @example, @method, @returns, etc...

Oops, I misread the diff, sorry. This only replaces @ within code fences. I think we also need to deal with code blocks not in triple backticks (you can indent exactly 4 spaces from the normal comment indentation and also be considered a code block). Though I don’t know how common this is in Ember...

okuryu commented 5 years ago

Is this a problem that YUIDoc should fix?

cibernox commented 5 years ago

@rwjblue If you think this can be merged as is, I'll merge it and release a new version today

pzuraq commented 5 years ago

@okuryu unfortunately YUIDoc is a dead project (hasn’t merged a commit in 4years or so now)

okuryu commented 5 years ago

@okuryu unfortunately YUIDoc is a dead project (hasn’t merged a commit in 4years or so now)

Yes. If this is a bug that should be fixed in YUIDoc, I thought I could cooperate.

pzuraq commented 5 years ago

Ah, didn't realize you were a maintainer! Let me see if I can adapt my fix to the existing code, would love to fix this upstream!

okuryu commented 5 years ago

Thanks. If you are in a hurry to fix this issue, please free to merge this PR. Fixing the upstream are also welcomed. I think I can take a look too.

pzuraq commented 5 years ago

Yeah, I think this would still be good to merge, since the upstream fix may require more changes (for instance to handle indented markdown examples, or @example examples). This unblocks us locally, but I'll definitely make a PR upstream as well to at least add this functionality, and try to take a stab at more general fixes as well.

cibernox commented 5 years ago

Published in 0.9.0