Hi William,
On 04/11/10 01:23 pm, William wrote:
Thanks for your review and your helpful suggestions.
Writing comments forces me to think better (like the teacher generally
learns most of a lesson).
On Apr 11, 3:11 am, Rob Hamerling<[email protected]> wrote:
Why not let the compiler do the low level work?
if target_cpu == PIC_16 then
TMR0 = timer0_load -- 16-bits timer0
else
TMR0 = byte(timer0_load) -- 8-bits timer0
end if
Thanks for the suggestion, but I wanted to make certain that the
registers are loaded in the proper order, as required by the
datasheet.
Aha! I didn't know about the prescribed sequence!
You might add a comment in the code (to prevent that the code is
simplified / broken!)
1. Registers are declared in uppercase in the device files, so for
consistency a library should use uppercase as well.
True, but I was trying to keep the style of the original library. But
since you brought it up, I'd like to see timer0_isr_interval.jal
improved so that it will work on 18F chips ( see issue #111) -- but I
didn't have time right now to re-test with 16F, so I left it alone.
OK.
Another thing I'd don't like to see in a library, is the setting of
global interrupt enable-- that should be left for the main program,
shouldn't it? What if I have other devices to set up before I want to
enable global interrupts?
Good point! But how to enforce users to do that? I'm pretty sure we will
receive reports that program's don't run (anymore) when we remove the
GIE setting from all libraries. And our samples will have to be updated
as well.
2. Some comments just above a procedure or function describing its
functionality will generate (better) documentation (I'm afraid many
libraries are suffering of such comments!).
Tell me more about this. I'm not sure I understand.
The html documentation found in /jalllib/doc/html is generated
automagically (by jallib.py) from comments in the source files. This
puts some requirements on the comments. One rule is that it should
immediately preceed the function, procedure, variable, etc. (and start
with a blink line or a comment line with only '--'). This implies also
that comments should not contain blank lines.
This applies also to the sections in the header. For example the text of
'Description:' should be contiguous (no blank or empty comment lines).
If you want a space line in the generated documentation put a 'double'
comment line: ('-- --') in your comments.
Many libraries need to be revised....
There are 2 wikis: JalApiWelcome and UsingJalApiWrapper which may be of
help in this respect.
Regards, Rob.
--
Rob Hamerling, Vianen, NL (http://www.robh.nl/)
--
You received this message because you are subscribed to the Google Groups
"jallib" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/jallib?hl=en.
