Do you put examples/ directory with sample code for integrating your library?

This is one of the really nice things about Go.

It has built in support for examples in the testing framework. blog.golang.org/examples

So you can put stuff like this in your code

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}

And they will automatically appear in the documentation.

Example

The advantage of this over textual documentation (which often diverges from reality) is it is checked to be syntactically correct by the compiler and checked that it actually does what it says it does by running it as a test.

I tend to make reference implementations in addition to or instead of sample code and examples for libraries. I made a command-line tool for linguist and a command line tool and standalone web application using vibrant and included them in the same repo as the library code.

It's nice to provide a high-level overview of an API and its functionality so users can see right away if it does something useful for them (hopefully what they've been looking for) and having something like godoc to document the API is invaluable, but I personally like to look at a full, working implementation in order to learn how to use a library and not have to fill in the blanks from minimal toy examples.

Dogfooding also helps with development and the only reason I ever make a library is because I want to use it anyway. I suppose if you're making a general-purpose library (that does string formatting or logging or vector math or something) or one with a wide surface area (like opengl, vulkan) then minimal examples make more sense, but if it does one highly specialized thing I think it's nice as a user to be able to see it in action right away (as an application) before using it programmatically (as lines of code)

That's just like my opinion man
-tso

Yeah, I think it's a good practice, especially when the usage of a library is not trivial. I really appreciate libraries that do this, it's nice to see a full working example that you can download and run. A while ago, following that example, I published this library with an examples folder.

If you have examples, you should re-run the them and verify the results for each commit.