I imagine there are repeated issues like this. These may be hard to generalize for students to accomplish in GCI tasks. I believe what we are getting is better than what we had, and we can make the minor fixes like making proper sentences, relabelling parameters properly, etc as we go. <br>
<div class="gmail_extra"><br><br><div class="gmail_quote">On Thu, Dec 6, 2012 at 3:24 AM, Sebastian Huber <span dir="ltr"><<a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-brains.de</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div class="im">On 12/05/2012 04:52 PM, Gedare Bloom wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
diff --git a/cpukit/rtems/include/rtems/<u></u>rtems/dpmem.h<br>
b/cpukit/rtems/include/rtems/<u></u>rtems/dpmem.h<br>
index a4cf251..e305b31 100644<br>
--- a/cpukit/rtems/include/rtems/<u></u>rtems/dpmem.h<br>
+++ b/cpukit/rtems/include/rtems/<u></u>rtems/dpmem.h<br>
@@ -84,13 +84,24 @@ RTEMS_DPMEM_EXTERN Objects_Information<br>
_Dual_ported_memory_<u></u>Information;<br>
void _Dual_ported_memory_Manager_<u></u>initialization(void);<br>
<br>
/**<br>
- * @brief rtems_port_create<br>
+ * @brief RTEMS Create Port<br>
</blockquote>
<br></div>
I would prefer to have a complete sentence as a brief description, e.g. "@brief Creates a port into a dual-ported memory area.".<div class="im"><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
*<br>
* This routine implements the rtems_port_create directive.<br>
</blockquote>
<br></div>
What is the use of such a sentence?<div class="im"><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The port<br>
* will have the name name.<br>
</blockquote>
<br></div>
This is duplicated with the parameter description. If we really want to duplicate this, then Doxygen has the "@a" tag to mark argument names, e.g. "The port will have the name @a name."<div class="im">
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
The port maps onto an area of dual ported<br>
* memory of length bytes which has internal_start and external_start<br>
* as the internal and external starting addresses, respectively.<br>
* It returns the id of the created port in ID.<br>
+ *<br>
+ * @param[in] name is the user defined port name<br>
</blockquote>
<br></div>
I would prefer to have a complete sentence as a parameter description, e.g. "@param[in] name The port object name."<div class="im"><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+ * @param[in] internal_start is the internal start address of port<br>
+ * @param[in] external_start is the external start address of port<br>
+ * @param[in] length is the physical length in bytes<br>
+ * @param[in] id is the address of port id to set<br>
</blockquote>
<br></div>
The id is an output parameter, e.g. "@param[out]".<div class="im"><br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
+ *<br>
+ * @return This method returns RTEMS_SUCCESSFUL if there was not an<br>
+ * error. Otherwise, a status code is returned indicating the<br>
+ * source of the error. If successful, the id will<br>
+ * be filled in with the port id.<br>
</blockquote>
<br></div>
I would prefer a listing of return status codes, e.g.<br>
<br>
* @retval RTEMS_SUCCESSFUL Successful operation.<br>
* @retval RTEMS_INVALID_NAME The name is invalid.<br>
* @retval RTEMS_INVALID_ADDRESS The id pointer is NULL, the internal start<br>
* address is not aligned, or the external start address is not aligned.<br>
* @retval RTEMS_TOO_MANY Cannot create port object.<div class="im"><br>
<br>
<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
*/<br>
rtems_status_code rtems_port_create(<br>
rtems_name name,<br>
</blockquote>
<br>
<br></div>
-- <br>
Sebastian Huber, embedded brains GmbH<br>
<br>
Address : Obere Lagerstr. 30, D-82178 Puchheim, Germany<br>
Phone : <a href="tel:%2B49%2089%2018%2090%2080%2079-6" value="+4989189080796" target="_blank">+49 89 18 90 80 79-6</a><br>
Fax : <a href="tel:%2B49%2089%2018%2090%2080%2079-9" value="+4989189080799" target="_blank">+49 89 18 90 80 79-9</a><br>
E-Mail : <a href="mailto:sebastian.huber@embedded-brains.de" target="_blank">sebastian.huber@embedded-<u></u>brains.de</a><br>
PGP : Public key available on request.<br>
<br>
Diese Nachricht ist keine geschäftliche Mitteilung im Sinne des EHUG.<br>
<br>
<br>
______________________________<u></u>_________________<br>
rtems-devel mailing list<br>
<a href="mailto:rtems-devel@rtems.org" target="_blank">rtems-devel@rtems.org</a><br>
<a href="http://www.rtems.org/mailman/listinfo/rtems-devel" target="_blank">http://www.rtems.org/mailman/<u></u>listinfo/rtems-devel</a><br>
</blockquote></div><br></div>