Reply to topic

[General FOSS workflow] File- and folder-level documentation

1

Votes
1
0
User avatar dzeri
Registered Member
Posts
1
Karma
0
OS
As a young software developer eager to make my contribution to FOSS (and KDE especially), I find it extremely difficult contribute to complex projects (like KWin), because aside from a few language/framework-specific norms, every project has its own convoluted project structure. Even if I generally know what I want to do, most of the time, I have to read most of the codebase to figure out which parts are relevant for the change I want to make. Even in enterprise-level projects I did work on, I wasn't required to know what every line of code does.

I'd like to propose a documentation framework like Doxygen, JavaDoc etc., which is language-agnostic, basically just documenting what each file is about, and how the project structure is laid out. I imagine this could be done with a dotfile in each directory, which describes the files and folders contained in it, so that each developer can focus on their own part of the code. Alternatively, it could be done in a central location for those who don't like clutter. This info would then be compiled to a web page like other doc. frameworks, but I could see how IDE integration would make this really useful.

I'm willing to start this project on my own if there isn't something like this already out there, and if there is community interest for it. It would be cool to make the project self-describing, so people could use the tool while contributing to it. Anyway, let me know what you think, this is my first post on the forum!
User avatar Mamarok
Manager
Posts
4847
Karma
12
OS
I strongly suggest you take this up directly with the KDE Docs team via their mailing list, they welcome documentation contributors.

FWIW: Doxygen is already in use AFAIK.


Currently running Kubuntu 20.04, Plasma 5.18.5, Frameworks 5.68.0, Qt 5.12.8, kernel 5.4.0-42
FWIW: it is always useful to state the exact Plasma version and distribution when asking questions in this forum, makes it easier for us to help ...

 
Reply to topic

Bookmarks



Who is online

Registered users: Baidu [Spider], Bing [Bot], claydoh, Google [Bot], irvingarrietavazquez, jmacleod, koffeinfriedhof, lagunacreek, matemat, quisimodo, sanecito, semper, Sogou [Bot], steveblezy, Yahoo [Bot]