5 ms·

So here's an example of the string package: https://pkg.go.dev/strings https://pkg.go.dev/strings In what way would the JavaDoc @param/@return/etc annotations

So here's an example of the string package: https://pkg.go.dev/strings https://pkg.go.dev/strings In what way would the JavaDoc @param/@return/etc annotations actually help? What Godoc has is more than suitable for the vast majority of cases.

pjmlp 4y ago
They provide the parsing engine with better clues for the AST that is given to the JavaDoc agent (aka doclet), which allows to customize the document generation process.
- throwawaylala1 4y ago
  Which didn't answer my question at all. Adding more structure to the AST with @param/@return/whatever doesn't make for better documentation. It's useless crap in a real world scenario.
  - pjmlp 4y ago
    Let me guess, another ACME fan that like Rob Pike doesn't use anything fancy as editor, including syntax highlighting. That crap allows for tooling that Go will never have thanks community culture.
    - doctor_eval 4y ago
      With respect, the general level of day-to-day tooling for Go is way better than for Java. Go is designed to be easy to parse and easy to build tooling for. “That crap” is at least in part a reaction to the endless stream of DocTagFactoryFactoryFactories patterns that came out of the Java world. While I think Java is a decent language with a good ecosystem, I’m completely over the idea that the only way to do things is the Java Enterprise(tm) way.
    - throwawaylala1 4y ago
      I use VIM and didn't even know ACME editor existed. Keep building strawmen, I'll be building software.
marcosdumay 4y ago
Have you seen the IDEs that show that documentation for the variables due to the position they take on the function call? What is on that documentation site you linked is just a text formatting guide, it's absolutely not enough to get a powerful documentation system. But yeah, it's simple.
- throwawaylala1 4y ago
  I have. My editor also gives me documentation for every function that I need. Plain text is more than enough for that use. What kind of function documentation are you reading inline lol? Does it have like 30 function arguments?

pjmlp 4y ago

They provide the parsing engine with better clues for the AST that is given to the JavaDoc agent (aka doclet), which allows to customize the document generation process.

throwawaylala1 4y ago
Which didn't answer my question at all. Adding more structure to the AST with @param/@return/whatever doesn't make for better documentation. It's useless crap in a real world scenario.
- pjmlp 4y ago
  Let me guess, another ACME fan that like Rob Pike doesn't use anything fancy as editor, including syntax highlighting. That crap allows for tooling that Go will never have thanks community culture.
  - doctor_eval 4y ago
    With respect, the general level of day-to-day tooling for Go is way better than for Java. Go is designed to be easy to parse and easy to build tooling for. “That crap” is at least in part a reaction to the endless stream of DocTagFactoryFactoryFactories patterns that came out of the Java world. While I think Java is a decent language with a good ecosystem, I’m completely over the idea that the only way to do things is the Java Enterprise(tm) way.
  - throwawaylala1 4y ago
    I use VIM and didn't even know ACME editor existed. Keep building strawmen, I'll be building software.

marcosdumay 4y ago

Have you seen the IDEs that show that documentation for the variables due to the position they take on the function call? What is on that documentation site you linked is just a text formatting guide, it's absolutely not enough to get a powerful documentation system. But yeah, it's simple.

throwawaylala1 4y ago
I have. My editor also gives me documentation for every function that I need. Plain text is more than enough for that use. What kind of function documentation are you reading inline lol? Does it have like 30 function arguments?