This repository has been archived by the owner. It is now read-only.

doc: colorize deprecated api notes #3898

Closed
wants to merge 1 commit into
from

Conversation

Projects
None yet
3 participants

API stability notes are very easy to overlook since they are the same
color as other code snippets. Likewise, deprecated and non deprecated
api look the same and give no visual feedback (other than a number
change) that one should not use the particular api. Using red for the
outline of deprecated api notes brings attention to the fact they are
deprecated.

doc: colorize deprecated api notes
API stability notes are very easy to overlook since they are the same
color as other code snippets. Likewise, deprecated and non deprecated
api look the same and give no visual feedback (other than a number
change) that one should not use the particular api. Using red for the
outline of deprecated api notes brings attention to the fact they are
deprecated.
Member

bnoordhuis commented Aug 21, 2012

Can't this be solved at generation time?

isaacs commented Sep 10, 2012

Agree with @bnoordhuis's leading question.

I like the idea of colorizing these, and not just for deprecation, necessarily, either. But, it should just add the class in the tag when it generates it. Check out the tools/doc/ program for the bits that make the doc markup.

So the issue is that the html is generated all at once. The way it is done currently does not expose a way to just "insert a class" into the tag. One possible solution is to update the marked package to the version that calls a callback for highlighed areas (see readme https://github.com/chjj/marked). Then wrap the passed in code using a tag and class we control. And one other way would be to read the generated html file into jsdom (or similar) and do the above except at generation time versus render time.

Member

bnoordhuis commented Sep 12, 2012

Updating the markdown parser sounds like the best option.

luk- added a commit to luk-/node that referenced this pull request Dec 28, 2012

Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.

luk- added a commit to luk-/node that referenced this pull request Dec 28, 2012

Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.

isaacs added a commit that referenced this pull request Dec 28, 2012

Colorize API stabilitity index headers in docs
Noted in @shtylman's #3898, API stability notes are easy to overlook
in the html documentation. This can be especially troublesome if the API
is deprecated. This commit gives visual feedback by adding in a class
to the html docs when they're generated. The API headers with
corresponding colors are also listed in the 'About this Documentation'
page for easy reference.

@defunctzombie defunctzombie deleted the defunctzombie:doc-color branch Dec 28, 2012

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.