3 ms·

Isn't that all javadoc did all those years ago?

eternalban 6y ago
Still does. Example: https://docs.oracle.com/en/java/javase/11/docs/api/index.html https://docs.oracle.com/en/java/javase/11/docs/api/index.htm... https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/nio/file/package-info.java https://github.com/openjdk/jdk/blob/master/src/java.base/sha... I think Gophers borrowed the idea of generating docs from header/source comment from Java. Java itself spec'd it in 1996. Where did Gosling and friends got the idea, I don't know. It may have precedents either in Sun's other languages or possibly an earlier precedent. Some relatively minor differences: In Go, documentation is externalized IFF top level code (function, type, var defs and declarations) immediately follows a comment line. In Java comments have two forms. The comment form using two asterisks is externalized. In Go comments (iirc) support some very basic text styling (of the generated doc). In Java externalized comments can use a basic set of markup ala HTML. This includes comment level hyperlinks to javadocs of referenced elements. Having used both languages rather extensively, Go's approach lends itself to CLI usage. Java provides richer markup and hyperlinks via java and is much better for someone who wants to explore the API via documentation.
- gostsamo 6y ago
  Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.
  - eternalban 6y ago
    I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs: http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.... On page 309 the `Metaclass Protocol` is defined. This class has a property “comment” [with value semantic of] ‘commentString’. So possibly they got it from Smalltalk. Don’t know.
    - pjmlp 6y ago
      If you search the book you will find samples like: sum: xValue with: yValue "sums two values" ^ xValue + yValue That is where commentString gets used. Several Lisp variants also have a similar approach.
      - eternalban 6y ago
        I fiddled around with SmalltalkAgents back in the day. Don’t remember how the doc was surfaced though. This product probably deserves its own hn post: http://preserve.mactech.com/articles/mactech/Vol.10/10.04/SmalltalkAgents/index.html http://preserve.mactech.com/articles/mactech/Vol.10/10.04/Sm...
        pjmlp 6y ago
        Indeed, it looks quite interesting

Still does. Example: https://docs.oracle.com/en/java/javase/11/docs/api/index.html https://docs.oracle.com/en/java/javase/11/docs/api/index.htm... https://github.com/openjdk/jdk/blob/master/src/java.base/share/classes/java/nio/file/package-info.java https://github.com/openjdk/jdk/blob/master/src/java.base/sha... I think Gophers borrowed the idea of generating docs from header/source comment from Java. Java itself spec'd it in 1996. Where did Gosling and friends got the idea, I don't know. It may have precedents either in Sun's other languages or possibly an earlier precedent. Some relatively minor differences: In Go, documentation is externalized IFF top level code (function, type, var defs and declarations) immediately follows a comment line. In Java comments have two forms. The comment form using two asterisks is externalized. In Go comments (iirc) support some very basic text styling (of the generated doc). In Java externalized comments can use a basic set of markup ala HTML. This includes comment level hyperlinks to javadocs of referenced elements. Having used both languages rather extensively, Go's approach lends itself to CLI usage. Java provides richer markup and hyperlinks via java and is much better for someone who wants to explore the API via documentation.

gostsamo 6y ago
Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.
- eternalban 6y ago
  I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs: http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.pdf http://stephane.ducasse.free.fr/FreeBooks/BlueBook/Bluebook.... On page 309 the `Metaclass Protocol` is defined. This class has a property “comment” [with value semantic of] ‘commentString’. So possibly they got it from Smalltalk. Don’t know.
  - pjmlp 6y ago
    If you search the book you will find samples like: sum: xValue with: yValue "sums two values" ^ xValue + yValue That is where commentString gets used. Several Lisp variants also have a similar approach.
    - eternalban 6y ago
      I fiddled around with SmalltalkAgents back in the day. Don’t remember how the doc was surfaced though. This product probably deserves its own hn post: http://preserve.mactech.com/articles/mactech/Vol.10/10.04/SmalltalkAgents/index.html http://preserve.mactech.com/articles/mactech/Vol.10/10.04/Sm...
      - pjmlp 6y ago
        Indeed, it looks quite interesting