Subject: [LON-CAPA-dev] Commenting standards.

From: Ron Fox <[email-masked]>
Date: Tue, 28 May 2002 23:32:37 -0400

For posterity, I wanted to summarize the commenting standards we talked 
about, and agreed to
start implementing.  I think it would also be wise, when we're doing 
significant work inside existing
code to bring that code into compliance.  I don't think it's necessary 
to mount a concerted effort to bring all
code into compliance now... just as we work on it, update.

-  Each file will begin with a comment header.  This header contains:
A copyright notice
Attribution of the initial author
One paragraph explanation of what the code in the module does in POD format.
Change Log
- Each sub will begin with a comment header in POD format.  This header 
describes:
Purpose of the sub (paragraph).
Parameters including: Name, data type, direction (e.g. in, out, 
modified), Purpose
Return value (type, purpose).
- Each outer level block of a sub, or main leve code starts with a 
comment describing what the block does.
- Additional documentation not encompassed by all of this will be in POD 
format at the end of the module.

On the whole, most modules already have this information, however in pod 
form, collected at the bottom of the
module.  Distributing this commenting so that documentation is close to 
what is documented should improve code
readability.
    Loncommon was mentioned as a module which has many of the features 
described by this standard.  I've
undertaken to take the module I'm working on: loncfile.pm and, after 
looking at loncommon turn it into a reference
model for the commenting standard.

Ron.

---

From: Scott Harrison <[email-masked]>
Date: Wed, 29 May 2002 14:10:08 -0400

Dear All:

> On the whole, most modules already have this information,

Actually, I think only about 10% of all the Apache perl modules have any
POD documentation.

I do agree with distributing the pod documentation throughout the subroutines.

(Note that each POD subsection must begin with '=pod'.
 Quite often, people just start with '=head2' or some other
 POD statement.)

Regards,
Scott

-- 
Scott Harrison, [email-masked]

---

From: "B. Minaei" <[email-masked]>
Date: Thu, 27 Jun 2002 12:58:15 -0400

Hi evrybody,

I am working on extracting the following feature from student data or
activity.log

"Participating in the communication mechanisms, vs. those working alone."

I found that fuction xmlend() in lonxml brings all discussion about a
particular problem in the end of it.

Is there anybody knows any function to find the discussion of a particular
student about a particular problem.

When we dump the student data in a big hash with dump function is the
discussion data are inculded in this data?

Or How we can find it from activity.log data?

Behrouz

---

From: Guy Albertelli II <[email-masked]>
Date: Thu, 27 Jun 2002 13:18:50 -0400 (EDT)

Hi Behrouz,

> particular problem in the end of it.

Yep.

> student about a particular problem.

The function that is grabbing the data is:

%contrib=&Apache::lonnet::restore($symb,$ENV{'request.course.id'},
                    $ENV{'course.'.$ENV{'request.course.id'}.'.domain'},
		    $ENV{'course.'.$ENV{'request.course.id'}.'.num'});

Which means all class contributions are being stored in a hash by symbs
with the name of the cource id in the course's home directory.

For example the PHY 183 course, has an internal name of
2964385f9033c63msul1

Thus it's 'request.course.id' is msu_2964385f9033c63msul1

So all of the discussion data is stored in the 
msu_2964385f9033c63msul1.db in the
lonUsers/msu/2/9/6/2964385f9033c63msul1
directory.

You can dump this data with 

&Apache::lonnet::dump('msu_2964385f9033c63msul1','msu','2964385f9033c63msul1')

> discussion data are inculded in this data?

There will be timestamp information like with homework data commits,
as it uses the store/restore mechanism for generating the information,
and store automatically adds a commit timestamp.
(Notice that xmlend uses the time stamp to add the time information to
the page:

$discussion.='<p><b>'.$sender.'</b> ('.
	     localtime($contrib{$idx.':timestamp'}).
	     '):<blockquote>'.$message.
             '</blockquote></p>';
)

-- 
[email-masked]          BM: n^20 t20 z20 qS 
Guy Albertelli -7-8-4-  O-
    I would love to but . . . I'm building a pig from a kit.