Since the original message kind of wasn’t placed that well in pumpkin-dev and a lot of messages were written since then, here‘s a link to the thread:
#pumpkin-dev message
#Make it mandatory to write function and logic documentation when contributing to pumpkin
dusty bane
dusty bane
Remember to vote in the original thread, you can also upvote this ^^
First poll link (second is below the first one):
#1351099930764120064 message
dusty bane
This will also help reducing the time writing documentation later on because most of the work is already done in chunks of documentation with every pr
dusty bane
@trim jewel I think this is almost a unanimous decision after three days. Poll results seem pretty clear. Lemme know what you think tho and obviously you have the last say ^^
When you give the go, I‘ll start writing some guidelines
dusty bane
I think referencing source code would be better
Sure thing, I can link stuff like that but a separate guide still doesn’t hurt when trying to mimik a consistent documentation style
remote tide
Sure thing, I can link stuff like that but a separate guide still doesn’t hurt w...
Ye, we need documentation, but writing documentation is super annoying lol
dusty bane
Ye, we need documentation, but writing documentation is super annoying lol
I agree but I hope the annoyance is worth it 😂
I also think it just takes some time to get used to writing your thoughts down while writing code. This way you already have a base of documentation that can ease the annoyance when simply fixing grammar or sentence structure
remote tide
imo writing documentation is easier afterhands that while doing something though
But I guess you could implement first then write
dusty bane
I like both ways sometimes, the important part is that it is present during PRs
Sometimes I actually prefer to write basic documentation before ever touching code when I just want to structure my logic because code gets complicated in no time
bronze pumice
imo writing documentation is easier afterhands that while doing something though
but afterwards nobody does it...
how do you attribute the responsibility for documenting a piece of code after it's merged and done?
sleek scaffold
git blame
dusty bane
how do you attribute the responsibility for documenting a piece of code after it...
I agree. What if the original maintainer of a specific piece of code is no longer maintaining it. Then someone else has to figure out what’s happening and without documentation that is a pain
bronze pumice
I agree. What if the original maintainer of a specific piece of code is no longe...
Exactly. Git blame won't help with that either. It would be a pain trying to contact the developer who wrote the code.
dusty bane
Or, just read the code lol
Yes, rust makes it particularly easy sometimes to understand stuff but at the same time documentation doesn’t hurt and actually causes less headache while figuring out what’s happening
bronze pumice
Or, just read the code lol
Yes, code should ideally be self-documenting but in reality that's often not the case. Reading your own code is always easy. Also to grasp overall concepts documentation should exist. For example explaining the workings of a module.
dusty bane
@trim jewel I’m currently a bit busy with university stuff but this still seems relevant and wanted by the community. If you‘re fine with this proposal, I‘ll work on some guidelines and general recommendations for documentation when I‘m free
wild falcon
I know that could be a bit of a hassle at the beginning since it needs to be done for existing code too but a simple "rust" way of doing this is:
#![warn(missing_docs)]
#![warn(clippy::missing_docs_in_private_items)]
And knowing that a PR is not accepted if linter failed, well this could force user
(Homever it's a brutal way)
remote tide
I know that could be a bit of a hassle at the beginning since it needs to be don...
I def don’t think every function needs docs
I think a markdown file in each dir is good enough, I’m gonna do that for the inv at least
dusty bane
I def don’t think every function needs docs
I kind of disagree. Every function has a reason to exist and should contain the documentation needed to understand it without needing to looking up additional resources (this includes self-documenting code) or even if the documentation is just one line
Moving documentation into a markdown file outside of the current function scope could confuse, slow down or even disrupt the coding experience through uncertainty, complexity and issues with direct readability
I‘m not saying documentation for each function should be so and so long. I‘m saying, every function needs at least a bit of care with documentation, even just a one liner is enough sometimes
remote tide
Markdown file gives more of a understandingh as a whole tho if you're looking at the code the first time
remote tide
I‘m not saying documentation for each function should be so and so long. I‘m say...
Maybe public functions in thate case
dusty bane
Markdown file gives more of a understandingh as a whole tho if you're looking at...
I get and like the idea generally but that wouldn’t replace the necessity of in scope documentation
remote tide
I get and like the idea generally but that wouldn’t replace the necessity of in ...
Ye, maybe comments can refrance a position in the markdown file, not sure
dusty bane
Code and docs should have a symbiotic relationship, each flowing naturally into the other while reading a function. That’s the ideal I‘m referring to
remote tide
Ye, function hover examples are great
dusty bane
Ye, maybe comments can refrance a position in the markdown file, not sure
That would include an extra step outside of the current scope. I’m generally like this for bigger documentation describing the overall idea behind a feature and how it works. I just would use it as the main resource but as an addition. The functions themselves should be documented in scope, I believe 🤔
dusty bane
Thank you for the feedback :)
remote tide
np
wild falcon
But everyone hates writing docs lol
That why i personnaly don't write my code docs... llm do it for me (the only thing with commit where i use llm)
dusty bane
But everyone hates writing docs lol
I get that, totally. I just don’t like the consequences of not doing it, so I have to force myself 😂
remote tide
That why i personnaly don't write my code docs... llm do it for me (the only thi...
Ye, smart idea actually, Not sure how good llms are at writing docs for rust code though
dusty bane
Ye, smart idea actually, Not sure how good llms are at writing docs for rust cod...
It’s kind of meh-ish
remote tide
I get that, totally. I just don’t like the consequences of not doing it, so I ha...
Obfuscate the code to make yourself unfireable 
wild falcon
Ye, smart idea actually, Not sure how good llms are at writing docs for rust cod...
I think like every llm, it's ok, but sometimes out of nowhere it give you garbage
remote tide
I gave up trying to use llms to write rust code, but they are good at explaining rust types
hearty rampart
from all llm i tested for rust Grok seems the best
wild falcon
I gave up trying to use llms to write rust code, but they are good at explaining...
Oh me too, i don't use any llvm for writing any type of code, i've always found myself debugging more time than i would have take time to wrote code, but for things like comments, where i'm not very good for expressing in correct english (i'm french) i find it's a great tools
dusty bane
Obfuscate the code to make yourself unfireable <:thinkSmart:1323417257598124172>
Writing code and forget what it’s about and then come back to it not knowing anything about what you were trying to accomplish because your code logic is straight up bonkers
remote tide
Oh me too, i don't use any llvm for writing any type of code, i've always found ...
ye
wild falcon
Writing code and forget what it’s about and then come back to it not knowing any...
Yep, that's why i agree on the fact that: Code should self document too.
I don't think it's a choice between on end or another
