
HTMLDoc – a standard for documenting your HTML - conwy
http://usehtmldoc.org/
======
pizzaknife
isnt the purpose of html to be a means of describing information one wishes to
convey? At what point is describing the describing of information in order to
describe information no longer a self perpetuating loop? I am likely naive or
ignorant but isnt there little to no value, as well, to screen readers /
alternate html consumers, in terms of accessibility and such? So, i guess my
tl:dr is "why?"

edit: thinking deeper into this - this also conflicts with other
bastardizations of html comments, used by some apparatuses (gulp initially
comes to mind), which need specific, albeit semantically useless, comments as
a "hook" (for lack of a better term) to distribute precompiled stuffs and
such. Im not endorsing these prior bastardizations any more than I am
condemning this idea, rather just pointing out that as well meaning it may
have been to contrive this - to me at least, it reads as more shrapnel in a
handgrenade.

~~~
conwy
Thanks for your thoughts.

While I certainly believe in self-documenting code where possible, I think
there's a place for comments, and also for well structured comments.

I wouldn't recommend going haywire and commenting on every HTML element,
attribute, etc., any more than I'd recommend using any other language facility
or tool like a sledgehammer.

But that's not to say structured commenting isn't a useful tool for the right
situations. I have found the JSDocs in the code-base of Angular and other
libraries to be invaluable, on occasions where it wasn't possible to fully
convey the meaning in pure code.

