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.
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!
Note that with 32 bit refs we may have to align objects on multiples of 64 bits (i.e. 8 bytes) because boxed floating point numbers will be accessed faster (on some processors it is even required that 64 bit values are aligned on multiples of 8 bytes). This means that the address of objects has the low 3 bits equal to 0. We can thus stuff 8 different type tags in the lower 3 bits.
One neat trick we could use with 64 bit references is to use (some of) the NaN encodings to represent object references. Then there is no difference between a boxed and an unboxed floating point value. Accessing objects may however be slower (it remains to be seen how clever we can be with the encoding... perhaps the low 32 bits of a NaN can be used as an address).
I hope we will be able to abstract and modularize the object representation of the system so that it is easy to switch from one representation to another without major changes to the system. That way we can explore different representations easily.
Marc