Code Comments

[fdncred]

This is something to think about. Your typical code comment looks like this:

' SRC\pix1.c (282, 1)
' setPixMemoryManager()
' setPixMemoryManager(alloc_fn, dealloc_fn) as void
''' <summary>
''' Notes
''' (1) Use this to change the alloc and/or dealloc functions;
''' e.g., setPixMemoryManager(my_malloc, my_free).
''' (2) The C99 standard (section 6.7.5.3, par. 8) says
''' A declaration of a parameter as "function returning type"
''' shall be adjusted to "pointer to function returning type"
''' so that it can be in either of these two forms
''' (a) type (function-ptr(type, ...))
''' (b) type ((function-ptr)(type, ...))
''' because form (a) is implictly converted to form (b), as in the
''' definition of struct PixMemoryManager above.  So, for example,
''' we should be able to declare either of these
''' (a) void (allocator(size_t))
''' (b) void ((allocator)(size_t))
''' However, MSVC++ only accepts the second version.
'''  </summary>
'''  <param name="allocator">[in][optional] - use NULL to skip</param>
'''  <param name="deallocator">[in][optional] - use NULL to skip</param>

It shows up in visual studio as a run on sentence with no line breaks. Since xml comments do not support traditional line breaks, you might want to change the comments to something like this:

' SRC\pix1.c (282, 1)
' setPixMemoryManager()
' setPixMemoryManager(alloc_fn, dealloc_fn) as void
''' <summary>
''' Notes<para/>
''' (1) Use this to change the alloc and/or dealloc functions;
''' e.g., setPixMemoryManager(my_malloc, my_free).<para/>
''' (2) The C99 standard (section 6.7.5.3, par. 8) says
''' A declaration of a parameter as "function returning type"
''' shall be adjusted to "pointer to function returning type"
''' so that it can be in either of these two forms
''' (a) type (function-ptr(type, ...))
''' (b) type ((function-ptr)(type, ...))
''' because form (a) is implictly converted to form (b), as in the
''' definition of struct PixMemoryManager above.  So, for example,
''' we should be able to declare either of these
''' (a) void (allocator(size_t))
''' (b) void ((allocator)(size_t))<para/>
''' However, MSVC++ only accepts the second version.<para/>
'''  </summary>
'''  <param name="allocator">[in][optional] - use NULL to skip</param>
'''  <param name="deallocator">[in][optional] - use NULL to skip</param>

Everywhere you put <para/> it inserts a line break and a new line. Not a perfect solution but it may be better than 1 run on sentence.

[Phreak87]

Implemented in next release

[fdncred]

<para/> changes are working