Isn't emacs the first to do it? I have the vague memory of it self-advertising as self-documenting.
Re:Go modules have a v2+ problem
by eternalban on Thursday September 10, 2020 @02:59PM
(#24435450)
I don’t know about emacs but your comment prompted a search for Smalltalk-80 docs:
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.
If you search the book you will find samples like:
sum: xValue with: yValue
"sums two values"
^ xValue + yValue
Several Lisp variants also have a similar approach.
Re:Go modules have a v2+ problem
by eternalban on Friday September 11, 2020 @11:27AM
(#24443826)
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/Sm...
Example:
https://docs.oracle.com/en/java/javase/11/docs/api/index.htm...
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.