docs: add some documentation of the segment format and creation #6
Conversation
I basically wrote down what I understood from working through the code to get a feeling of what it does. I added some TODOs and might have gotten something wrong so this will very likely have a follow up commit to fix things.
|
Please note that I applied the "Comment Sentences" hint from the official CodeReviewComments wherever possible. |
|
I also payed some attention to the "Named Result Parameters" hint. |
| // Split generates a new segment recipient of future writes | ||
| func (bl *BigLog) Split() (err error) { | ||
| // Split creates a new segment in bl's dirPath using the maxIndexEntries of | ||
| // the currently active segment starting at the highest available offset+1. |
There was a problem hiding this comment.
using the maxIndexEntries of the currently active segment
that's kind of an implementation detail, the gist is that the maxIndexEntries remains the same, it could have been a fixed setting but since BigLog doesn’t have settings by itself I chose to derive it that way.
There was a problem hiding this comment.
how about this?
// Split creates a new segment in bl's dirPath starting at the highest
// available offset+1. The new segment has the same size as the old one
// and becomes the new hot (active) segment.
Alternatively its probably also ok here to omit the segment size altogether. This kind of information could be documented in the high level package documentation describing the file layout of a Biglog.
|
Niiiice! Let me know if you need any ideas on what to tackle. |
|
😄 yeah I kind of got inspired by watching your golang uk talk yesterday. I'm gonna continue to review and understand the code before I can even think of implementing something. Anyway it would probably be helpful to have some kind of platform to talk asynchronously about the code (apart from github issues). Any ideas? so far I have used gitter and google groups for this. If you feel this is overkill at this point I'll probably just write an email. |
|
Happy to hear that people are able to parse the firehose of words that the talk turned out to be 😅 I would not mind a google group netlog-dev, that would not require an extra account and the emails are still public for future reference. |
|
A google groups sounds good. As package owner I'll leave it up to you to create and probably also announce it in the README.md |
This will eventually be fixed in another pull request. Maybe this will be done via netlog/issues#7
I basically started with the example.go and wrote down what I understood from looking at the code. Before I go any further with this I wanted to submit a small pull request to get your feedback on this approach.
There is mostly just documentation going on and there should definitively be no logic change whatsoever but there are some instances were I renamed a variable to make it easier to see what is happening in the code.
Additionally I added some TODOs and since I'm very new to netlog its very possible that I have gotten something wrong so this will very likely have a follow up commit to fix things.
Let me know what you think
Friedrich :)