Reflections on using Go instead of D

[jfondren]

On Wednesday, 13 July 2022 at 05:39:24 UTC, Ola Fosheim Grøstad 
wrote:
> What I dislike is the auto generated documentation. D also has 
> this issue.
>
> Well written docs are so much better. Write the docs when 
> speccing out the API!
>
> Using doc generation for a standard library is just a terrible 
> idea.

In both languages it's possible for a tech writer to put a lot of 
well written documentation around the autogenerated stuff. Rust's 
stdlib docs are also 'generated' and they're steller, and all 
that prose is in giant comments in the files: 
https://doc.rust-lang.org/std/index.html

Having an amount of doc generation permits nice tooling to go 
with all that well written text that somebody could write if they 
wanted. For example from go, given this file:

```go
package main

import "fmt"

// add 1 to a number
func f(n int) int {
	return n + 1
}

func main() {
	fmt.Println(f(1))
}
```

You can query its documentation at the command line:

```
go$ go doc -u f
func f(n int) int
     add 1 to a number

go$ go doc -u main
func main()
go$ go doc fmt.Println
package fmt // import "fmt"

func Println(a ...any) (n int, err error)
     Println formats using the default formats for its operands 
and writes to
     standard output. Spaces are always added between operands and 
a newline is
     appended. It returns the number of bytes written and any 
write error
     encountered.

```

which could exist for D, or rather it probably does between dmd 
-D and dscanner and other IDE support that just isn't as 
immediate.