On 2010-06-07, at 9:29 , Marc Feeley wrote:
On 2010-06-06, at 10:10 PM, chevalma@iro.umontreal.ca wrote:
Erick and I would like to use the JsDoc tool to generate code documentation based on annotations inside comments. This would require that our file headers and functions/constructors be annotated according to the JsDoc annotation tags.
See the wiki at: http://code.google.com/p/jsdoc-toolkit/
I've annotated some sample files in the repository (see lowlevel/memory.js and ir/instructions.js), and updated the coding guidelines on Google Docs to explain how to do this.
I've looked at your samples, and it seems verbose. I have a hard time reading the comments because of all the markup around them. Is there a shortcut for "description" tags, since they are really frequent? It would be nice if by default (no tag) a /** comment was a description. Is it necessary to repeat the "author" information for each class? If we really need to know who wrote what, we have the git history.
I agree with Marc here. The @description tag is really unnecessary; it should just be the default. The @author for each class could be replaced with a @author for the file, and possibly overridden in individual classes in the (unlikely) event that a different author inserts classes in the file.
Marc, do you have an opinion on this? It would imply adding annotations to your parser code.
Yes I will update my source files when we agree on a particular documentation style.
What can be gained by restricting words to be 64 bits? Can't we simply have that as a parameter? The intel code generator I've written support 32 and 64 bit architectures.
That's the conclusion Erick and I came to as well. Perhaps we should simply have a configuration file that sets these sort of platform-specific behaviors... And if 32 bit pointers/values are faster even on 64 bit machines, we can set that by default, while still allowing 64 bit pointers/values.
Yes, I should have mentioned also that with 64 bit references (a better term than pointers/values) a heap can be up to twice the size of a heap with 32 bit references for the same objects. That means that if a computer has less than 8 GB of RAM it is better to use 32 bit references (i.e. with 32 bit refs you can have as many objects in 4 GB of the RAM as with 64 bit refs with 8 GB of RAM). I've encountered this problem with Gambit on one of my machines which has 6 GB of RAM. Even on a machine with slightly more than 8 GB of RAM it is likely that the 32 bit refs will be desirable because it leaves more free RAM for the OS and other applications. Let's not neglect the fact that currently it is very rare to see applications which need more than 4 GB of RAM (regardless of the language they are written in). 32 bit architectures are not dead yet!
I have to say that in Java VMs, we have had better success using the 'compressed addressing mode' (i.e. 32-bit pointers on 64-bit arch). Memory usage, in particular, was a huge problem when using 64-bit pointers on regular desktop machines. I therefore support allowing both 32 and 64 bit pointers in tachyon as well.
Bruno