Clean documentation from its examples, and use Go testing Examples

[ccoVeille]

I would like to suggest to move all these code extract to ExampleXXX method in the code.

https://go.dev/blog/examples

I think the documentation should only add links to them, and not provide 50+ lines example in Markdown fenced code blocks

Originally posted by @ccoVeille in https://github.com/gofr-dev/gofr/pull/1429#discussion_r1931741408

[ccoVeille]

Here are some real life examples of the situation we have right now with maintaining code examples in Markdown files

It needs to be arangodb as the package directory is arangodb. I would suggest keeping the name consistent ..either we use arango everywhere or arangodb. Originally posted by @coolwednesday in https://github.com/gofr-dev/gofr/pull/1429#discussion_r1935100756

Please update the documentation, now user needs to call ctx.ArangoDB.CreateDB(....) instead and so on ..... Originally posted by @coolwednesday in https://github.com/gofr-dev/gofr/pull/1429#discussion_r1935099742

Such feedbacks are often made, and I think finding a solution to extract/remove code from documentation would improve everything, avoid left behind error/code in documentation after a refactoring/code review and would ease code review process

[aaryyya]

assign

[aryanmehrotra]

Hey @aaryyya we need to discuss more on this on what has to be done as its unclear we would need some examples before we decide to move forward with this.

@Umang01-hash @ccoVeille can you add some more context or one example from gofr example so we can triage and proceed with this.

[aaryyya]

as in all the maintainers need to discuss? or you need me in the discussions?

[aryanmehrotra]

@aaryyya you can also add your points and examples, it would be helpful.

[ccoVeille]

It's about this https://go.dev/blog/examples

Here is an example in one of my repository

Here you will find the code of safecast.ToInt

And here you will find the testable example of ToInt8 https://github.com/ccoVeille/go-safecast/blob/e16fe30f4cfeb6ac5d66c47c44d76a08d54b2ffd/examples_test.go#L21

This way the example is rendered like this https://pkg.go.dev/github.com/ccoveille/go-safecast#ToInt8

Here is an example in gofr, where the Example are provided as a comment

https://github.com/gofr-dev/gofr/blob/2cdddeffe3135f27206e2b6bfe2601f4414fac01/pkg/gofr/datasource/arangodb/arango.go#L208-L234

There are many caveats with this option that is widely used in gofr codebase:

• the documentation can be left out of sync, as a refactoring won't update text in the godoc of a method
• the code is displayed in a different way that is not the Go way, but as markdown

Here is how it get rendered

This is what this issue is about.

Of course, it's only what I would expect from a repository, it can be done the way you did, but it's not easy to maintain