Comments (9)
Is there another issue that's tracking documentation?
Right now, if you came to this library fresh, without the http://labix.org/mgo docs, you would not know how to Insert data nor get data out using a struct. Nor is there any clue that you can use a map (or not for that matter) instead of a struct.
from mgo.
Hi @djensen47
There's nothing tracking documentation at the moment, but feel free to open issues for specific things that you feel would benefit being included - we'll happily accept PRs for any improvements to the docs.
Regarding the example file, it's rendered in GoDoc, you don't have to go looking for the file so sticks with the "all in code" idea.
Dom
from mgo.
Hi @djensen47 - really sorry about the lack of a reply, I've been away at a conference for the last few days.
There's currently no plans for an accompanying site, it will add maintenance cost - personally I never looked at it! Is there something specific you used to rely on the labix site for? Perhaps we can find a way to work it in.
Dom
from mgo.
I believe we should have some documentation on readme, godoc etc. use cases, and stuffs. Right now this looks so empty.
from mgo.
It was useful for setup and usually a docs page is more straightforward than a giant godoc page.
Documentation is a necessity of maintaining any great open source project (which this is 😄). It doesn't have to be a separate site but at the very least the project needs a README and a godoc.
from mgo.
I can see your point! Saying that, as an open source project we'll happily look at PRs improving the docs 👍
We've added a couple of code examples on the GoDoc page but it could definitely be expanded - it's preferred to use GoDoc as it's checked within the test suite - if a PR would cause the example code to become out of sync with the examples (say, in the README) this would cause a build error and would prevent a merge.
This fork was originally performance & bug fix driven - it was expected users already used mgo and were looking for a drop-in replacement, hence the light README as there was very little to say - again, we'll happily review PRs changing this!
Thanks,
Dom
from mgo.
Hi @djensen47
There's no plans to add an accompanying site / spreading the documentation over several sources - it only makes it trickier for newcomers to find what they're looking for and more work to keep it all in sync. Go strongly encourages documentation within your code which is automatically available on godoc which makes it the go-to place for everyone.
The basic insert/read operations you describe can easily be covered by adding examples to the code where everyone with a copy of the repo can access them, even offline.
We'll happily accept a PR to improve documentation on godoc in general, or maybe a quick-start markdown file within this repo though it would have to provide significant value to justify having documentation outside the official godoc documentation.
Dom
from mgo.
Sorry, I wasn't clear ... I was literally just wondering if documentation is being tracked in other issues or if there is a tag? Some what to go about it in an organized manner.
it's preferred to use GoDoc as it's checked within the test suite
This was your original answer and it makes sense and I wanted to discuss that but forgot to say so (sorry). I would add that the Godoc route makes it easier to maintain.
Regarding the other stuff
it only makes it trickier for newcomers to find
I disagree. I've seen numerous examples from many programming languages where they do it right.
But I'm still totally on board with the Godoc approach. I've seen 2 or 3 Godocs that are complete and useful (which tells you the dismal state of Godoc docs) and that approach can definitely work.
The basic insert/read operations you describe can easily be covered by adding examples to the code where everyone with a copy of the repo can access them, even offline.
That file is really hard to see unless you know to look for it.
from mgo.
So regarding Godoc doc bugs, should I file them individually, open it for discussion, then submit a PR? Or do you have another approach in mind?
from mgo.
Related Issues (20)
- Query blocks with ChangeStream HOT 2
- Upsert doesn't work well with query where value is []byte format
- Expose dialInfo through a getter?
- High concurrency session copy does not release the connection and poolLimit is invalid
- Request: BSON stabilize ordering of map keys (instead of GoLang's random ordering) HOT 1
- Unwanted allocs in mgo
- Auto type assertion not working when fetching data
- Clean actions attribute of Bulk struct
- time.Parse HOT 2
- can any one tell me how to use $near to calculate lat,lng distance
- MongoDB index not being used when querying through mgo on mongoDB views
- }
- DropDatabase returns not master when seesion mode is Secondary
- mgo: FindAndModify create too many sockets
- error="SASL support not enabled during build (-tags sasl)" HOT 8
- Daemontools
- Panic With ObjectIdHex(s string)
- current
- BSON unmarshal unable to parse $date
- error="no reachable servers" HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from mgo.