feat: Add @deprecated annotation

[jbrubake]

Add a @deprecated tag (original patch written by @hyperupcall) to functions that renders like this:

# @description A deprecated function
# @deprecated Because it's old
deprecated-function() { echo; }

deprecated-function

DEPRECATED Because it's old

A deprecated function

[GB609]

I've got 2 issues i'd like to ask you to look at again.
Aside from that i think it is a useful addition.

[GB609]

Please use deprecatedText = render("strong", "DEPRECATED") instead.
shdoc tries to keep rendering styles separate from content. It might currently only support the github md-style, but it'd like to keep the concept.

[jbrubake]

I missed that that was possible. As a future thought it might be good to have a brief "contributing" guide that lays out things like this. I found myself having to read a lot more code than should be strictly necessary to understand how to add features

[GB609]

You are right about the contribution guideline. To be honest, i haven't thought about this so far, since i never expected someone to actually start contributing to my fork.

I've only created the fork to get some more features in which i felt were missing in upstream, so i didn't touch most of the boilerplate files (readme is the only exception) as that quickly becomes annoying to deal with when creating PRs for upstream.

I'm in a similar situation to you though, i also 'inherited' most of the code and had/have to struggle with it on several levels.

I'm also not sure where to go with it on the long run... try to bring stuff upstream (which i normally prefer), keep as is or detach the fork.

[jbrubake]

Upstream hasn't updated in 3 years with 18 open issues and 7 pull requests so it's probably safe to consider your fork the only active one. I find shdoc useful enough that I was about to start maintaining my own fork before I found yours

[GB609]

Thats likely true, although the number of issues and PRs doesn't always say all that much because basically anyone can just put up whatever (nonsensical) request. Not reacting to anything at all for years, however, certainly hints at inactivity (or an insufficient notification setup).

Anyway, i'll try to get a few basics overhauled at the weekend if i manage to get to it. I'm pretty busy currently and there's a few other tasks i'd like to finish which i've delayed and neglected a bit longer than i'd actually like to.

[GB609]

Please rebase the branch

[jbrubake]

Rebased (and fixed my initial wrong fix)

While testing this I keep seeing some oddities in how @description interacts with other tags and how order matters in ways that may not be intuitive. Probably something to look at later

[GB609]

It might be good to create a minimal reproducer for your odd behavior and make an issue of it.
Maybe as a test in a branch, or 2 files uploaded to the issue (input and expected output).

The basic problem is likely related to the way shdoc/awk maintain state of document blocks (which is pretty tricky with how awk variables work). It always has to distinguish none-shdoc comments from actual annotated comments, so there are some basic requirements about the order of appearance. I've also found out that most of the additional annotations just don't work when the current comment block doesn't contain a @description annotation as well, or when the @description comes afterwards, because there are some state resets at work then.

[jbrubake]

It might be good to create a minimal reproducer for your odd behavior and make an issue of it. Maybe as a test in a branch, or 2 files uploaded to the issue (input and expected output).

Good idea. I'll work on that when I get a chance.

The basic problem is likely related to the way shdoc/awk maintain state of document blocks (which is pretty tricky with how awk variables work). It always has to distinguish none-shdoc comments from actual annotated comments, so there are some basic requirements about the order of appearance.

I expect there is a fix to all this but it's probably going to be a significant refactor. Which is worth it but will take some thought. I'll create an issue to track this later

I've also found out that most of the additional annotations just don't work when the current comment block doesn't contain a @description annotation as well, or when the @description comes afterwards, because there are some state resets at work then.

That's basically what I've been noticing