My comments, would be: 1a. Converting the original Classic API specifications (RTEID or ORKID) into Asciidoc
Is reST as good at cross-referencing as doxygen? Cross-referencing is critical for low maintainence overhead and tracablility. We should try to have a script do most of the conversion work, and have the students polish the edges... There is a trac plugin for cross-referencing doxygen... http://trac-hacks.org/wiki/DoxygenPlugin Keeping with doxygen would also reduce the number of documentation languages a developer would need to know... I suspect that doxygen tags will outlast reST because of IDEs displayin doxygen tags to assist developers with coding 1b. head those down the path of being requirements Yes, we need to identify the format that will make the generation of the other documentation easy to automate. 1c. To ease readability, the format of the front matter could probably have the similar headings to: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap01.html The front matter should have the same general format as: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap01.html and A brief description of what a requirement would be: http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap13.html#tag_13_00_00_01 I really feel keeping this level of documentation in doxygen format in the headers would make it easier for eclipse users to find (when a user hovers over a function the comments above the function appear)... 2. Start applying doxygen to the BSPs? Could we use the functions in the simulator BSPs for the functions at the moment? When we decide what else should be a standard API, we can add those functions later... 3. Newlib changes... Yes, the restrict keyword sounds good... I'm not familiar enough with the null issue to have an opinion... Could we also have the students cross-reference functions in http://pubs.opengroup.org/onlinepubs/9699919799/idx/head.html to http://svnweb.freebsd.org/base/head/include/ to and http://svnweb.freebsd.org/base/head/lib/ to get newlib more compliant with the new POSIX? We might also ask the student to propose a location for where the cross-referenced files should go in newlib as well. 4. +1 on the getting-started! Could we also have the students generate screen-shots again? It would be easier to have students write the test-descriptions if we had the screen-shots (and once the test description is written we can remove them from the repository). 5. Where students would be really useful for forward compatibility is porting the existing rtems wiki pages to trac compatible format. To ease this, the students would need access to the wiki source of the pages (I know the plan was to lock the pages down, but I'd like to be sure it's possible to access the source during the code-in). It may also be helpful to identify a helper script... Thanks, Cindy ________________________________________ From: rtems-devel-boun...@rtems.org [rtems-devel-boun...@rtems.org] on behalf of Joel Sherrill [joel.sherr...@oarcorp.com] Sent: Wednesday, October 23, 2013 1:12 PM To: Gedare Bloom Cc: rtems-devel@rtems.org Subject: Re: Google Code In Schedule and Tasks On 10/23/2013 2:42 PM, Gedare Bloom wrote: > On Wed, Oct 23, 2013 at 2:46 PM, Joel Sherrill > <joel.sherr...@oarcorp.com> wrote: >> Hi >> >> Checking the timeline for GCI... >> >> 28 Oct - deadline for applications >> 1 Nov - organizations announced >> >> Our application is in. Thanks to those who helped me review >> and update the answers for the application. >> >> We now need to work on the task sets and update the wiki >> >> http://www.rtems.org/wiki/index.php/GoogleCodeInProjects >> >> We need some bulk tasks. These are one where a single set of >> instructions can be applied to multiple sets of files. We >> got massive improvements to our Doxygen with students last >> year doing this. Ideas include: >> >> + >> > Why convert to asciidoc? Per Amar, Sphinx/REST is a superset of asciidoc. That is supposed to be easy to process in web and database programs. As we head to using these as requirements, my long term goal is to trace them to code and tests. That will require processing them somehow. And.. I am begging for help defining that traceability process and automated management so we have high quality SW processes but don't overburden ourselves. >> + Continuing to add Doxygen if we left files undone from last year. >> > We could expand the scope. Would it be worthwhile to start applying > doxygen to the BSPs? Yes. If we prioritize the BSPs and define the pattern. :) > By the way, a request was made for a "search" bar for the generated > html from doxygen. Hmm.. that should be just a configuration setting. If someone knows it, just post what to change. >> + Add restrict keyword as necessary to newlib .h files. [NOTE: >> As scary as this is, OAR had a high school intern who started this.] >> > Is this easy to figure out where to put? The POSIX specification states where to put it. We know which files need to have it added. Our intern got that far and fixed some. Beyond that, we taught him cscope to find if there were architecture specific implementations to touch. This requires instructions to be written but we did this task with a student. >> + Add attribute notnull as appropriate to (a) Classic API. >> Consider similar task on POSIX and newlib. No comments? :) >> + BRL-CAD had a standing task which each student could ONLY DO ONCE. >> It would be to follow our GSOC hello world instructions and comment. >> This puts more users through the procedure and lowers our entry >> barrier. >> > Good idea. I thought so. >> Coding tasks tend to not get taken but eliminate a warning is a good one. >> >> -- >> Joel Sherrill, Ph.D. Director of Research & Development >> joel.sherr...@oarcorp.com On-Line Applications Research >> Ask me about RTEMS: a free RTOS Huntsville AL 35805 >> Support Available (256) 722-9985 >> _______________________________________________ >> rtems-devel mailing list >> rtems-devel@rtems.org >> http://www.rtems.org/mailman/listinfo/rtems-devel -- Joel Sherrill, Ph.D. Director of Research & Development joel.sherr...@oarcorp.com On-Line Applications Research Ask me about RTEMS: a free RTOS Huntsville AL 35805 Support Available (256) 722-9985 _______________________________________________ rtems-devel mailing list rtems-devel@rtems.org http://www.rtems.org/mailman/listinfo/rtems-devel _______________________________________________ rtems-devel mailing list rtems-devel@rtems.org http://www.rtems.org/mailman/listinfo/rtems-devel
