Status of ALSA documentation?
ALSA is not an easy code base to come to grips with so we should apply the kiss rule (keep it simple stupid) to help newbies coders get their heads around it.
Quoted 1 line
From my perspective the comments are not standardised enough. I haven't checked the code for a couple of months but last time I looked each file had a different approach to where and when comments were added.
IMO if the developers could agree on a standard layout for every file then new developers would have much more chance of understanding how things work. Simply a matter of repetition.
Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?
EG.
- How many hours per week are expected?
- What are the knowledge requirements?
- What are the legalities?
- What are the target responsibilties?
- What are the benefits?
I am interested in the web site maintainer depending on the above requirements.
As long as I can add it to my resume.
--
Patrick Shirkey - Boost Hardware Ltd
For the discerning hardware connoisseur Http://www.boosthardware.com Http://www.boosthardware.com/LAU/Linux_Audio_Users_Guide/
Quoted 43 lines · --- Kai Vehmanen
Quoted 4 lines · Kevin Conder
Quoted 3 lines
Quoted 2 lines
last time I checked, the ALSA developers were adding doxygen comments to the source code.
The best part of javadoc is that it adds very little overhead.
I'm confused. Is the ALSA project using javadoc or doxygen?
Good point. Javadoc is both a tool for extracting documentation (html) from Java code and a name for referring to the style of documenting (ie. putting documentation in the source code files). There are many tools for extracting javadoc-style documentations. Javadoc and doxygen are two well-known tools, but I've also used at least kdoc and scandoc. There are probably quite a few others available. Doxygen has been my personal favorite for a while now (for C, C++ and Java).
Quoted 4 lines
Quoted 3 lines
This may sound pessimistic, but a fact is that lots of time went to writing API docs for ALSA 0.3, 0.4 and 0.5. That time could have been instead spent on working on the code.
Are you implying that writing documentation is a waste of time?
No, no. I just think a short but up-to-date reference manual is a lot better than huge amounts of unmaintained documentation. I've used this minimal approach in ecasound and it has worked really well. There's quite a lot of documentation available (and all of up-to-date!), but not too much for me to maintain (= I can spend most of my time on fixing bugs, implementing new features and improving old ones; things that I really like to do).
For instance, let's say the following documents would exist:
- javadoc comments stored in CVS
- online implementation docs generated from the javadocs
- reference manuals for alsa-kernel and alsa-lib APIs; possibly SGML stored in CVS
- web-version of the manuals at www.alsa-project.org; generated from SGML-files
- tutorial for writing ALSA apps; web siteIf you now add a new feature, you might need to update all the above. If you redesign some part of the system, you will have to rewrite the related chapters. In any case you have to remember what is documented where so you know when you need to update something.
Quoted 14 lines
And just to make sure, these comments are aimed at ALSA as a free software project. In commercial software development the situation is completely different. There developers are expected to document their work and they get money from doing it.
Signature · 8 lines
http://www.eca.cx Audio software for Linux! _______________________________________________ Alsa-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/alsa-devel
_____________________________________________________________
Want a new web-based email account ? ---> http://www.firstlinux.net
_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel
Quoted 2 lines · Patrick Shirkey
Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?
Ok, do note that I'm not a member of the ALSA dev team, so I can't make any real claims. Hopefully the dev team agrees with at least some of what I'm about to say. :)
Quoted 4 lines
- How many hours per week are expected?
- What are the knowledge requirements?
- What are the legalities?
- What are the target responsibilties?
Like in most free sw project jobs, nobody can demand you any of the above. If someone has problems with how you do the job, or how much time you spend on the work, she should be prepared to work on it and do it better (the 'show me the code' attitude :)). But if you take the job, complaints _will_ be directed to you, whether justified or not. On the other hand, when you do your job well, people will appreciate it and also your opinions will have more weight.
In the end, it's probably Jaroslav who decides who has access to modifying www.alsa-project.org (he owns the domain).
Quoted 1 line
- What are the benefits?
Big salary, fast cars and beautiful women! (or at least, your bug reports might get a priority flag every now and then) ;)
Signature · 8 lines
http://www.eca.cx Audio software for Linux! _______________________________________________ Alsa-devel mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/alsa-devel
Quoted 10 lines · Patrick Shirkey
ALSA is not an easy code base to come to grips with so we should apply the kiss rule (keep it simple stupid) to help newbies coders get their heads around it.
Quoted 1 line
From my perspective the comments are not standardised enough. I haven't checked the code for a couple of months but last time I looked each file had a different approach to where and when comments were added.
IMO if the developers could agree on a standard layout for every file then new developers would have much more chance of understanding how things work. Simply a matter of repetition.
Apart from that what are the job requirements of an ALSA web maintainer and a documentation leader?
EG.
Quoted 7 lines
- How many hours per week are expected?
- What are the knowledge requirements?
- What are the legalities?
- What are the target responsibilties?
- What are the benefits?I am interested in the web site maintainer depending on the above requirements.
Actually, our web is based on apache and PHP3 scripts. Perhaps, we can move to python (nice language) or PHP4 in future. I've created a CVS repository for WWW contents. Each commit automatically updates the WWW pages, so we have good management system for web.
If you are interested to reorganize contents of ALSA web site, I can give you CVS write access and you can show your ideas in some subdirectory for clarification.
Anyway, I am ready to answer any questions regarding ALSA. It's obvious.
Jaroslav
-----
Jaroslav Kysela <[email protected]>
Linux Kernel Sound Maintainer
ALSA Project http://www.alsa-project.org
SuSE Linux http://www.suse.com
_______________________________________________
Alsa-devel mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/alsa-devel