search

webpack / webpack.js.org

Repository for webpack documentation and more!
https://webpack.js.org
Creative Commons Attribution 4.0 International
2.21k stars 3.31k forks source link

Comments are sometimes above and sometimes below what they describe #2662

Open lazarljubenovic opened 5 years ago

lazarljubenovic commented 5 years ago

For example, https://webpack.js.org/configuration/#options and https://webpack.js.org/plugins/module-concatenation-plugin/#debugging-optimization-bailouts.

image

image

Furthermore, sometimes a long comment is inlined, which cause an easily-avoidable horizontal scroll (see e.g previous screenshot). For example, https://webpack.js.org/plugins/context-replacement-plugin/#other-options.

image

Would be nice for consistency to have them always written in one way. I have multiple tabs open and I keep reading the wrong comment because of different styles :flushed:

EugeneHlushko commented 5 years ago

Hi @lazarljubenovic I dont think we should touch the configuration comments as they are very different to other places and we are going to update that section in rebuild branch.

But for the rest of code samples that are not "js-with-links" but instead plain javascript examples we could move all the comments to the top.

Do you think that would make sense for you use case?

lazarljubenovic commented 5 years ago

Yup, I think comments on top are the most common way to place it. I'll fiddle around with it these days.