DSDL documentation comments

Development & Maintenance
1

While working on the DSDL specification and its parser, I briefly pondered about automatic extraction of doc comments from DSDL definitions to facilitate automatic documentation of generated code. Currently, our code generators have no way of obtaining relevant comments from DSDL descriptions because they are simply discarded by the parser. Even though I am certainly not planning on implementing that anytime soon (although PRs are always welcome), that line of thought made me wonder about the optimal placement of comments. The following example shows the current arrangement:

# Domain name or IP address where the payload should be forwarded to.
# Note that broadcast addresses are allowed here, for example, 255.255.255.255.
# Broadcasting with masquerading enabled works the same way as unicasting with masquerading enabled: the modem
# node should take care to channel all traffic arriving at the opened port from any source to the node that
# requested masquerading.
# The full domain name length may not exceed 253 octets, according to the DNS specification.
# UAVCAN imposes a stricter length limit in order to reduce the memory and traffic burden on the bus: 45 characters.
# 45 characters is the amount of space that is required to represent the longest possible form of an IPv6 address
# (an IPv4-mapped IPv6 address). Examples:
#   "forum.uavcan.org"                              - domain name
#   "192.168.1.1"                                   - IPv4 address
#   "2001:0db8:85a3:0000:0000:8a2e:0370:7334"       - IPv6 address, full form
#   "2001:db8:85a3::8a2e:370:7334"                  - IPv6 address, same as above, short form (preferred)
#   "ABCD:ABCD:ABCD:ABCD:ABCD:ABCD:192.168.158.190" - IPv4-mapped IPv6, full form (length limit, 45 characters)
void2
uint8[<=45] destination_address

So there is a lengthy text followed by a padding field followed by the actual field we are discussing. Now, Cap’n’Proto, for example, recommends the opposite, where the doc comments are located after the described entity, arguing that it improves readability because one would have to see the commented entity anyway before reading the comment:

void2
uint8[<=45] destination_address
# Domain name or IP address where the payload should be forwarded to.
# Note that broadcast addresses are allowed here, for example, 255.255.255.255.
# Broadcasting with masquerading enabled works the same way as unicasting with masquerading enabled: the modem
# node should take care to channel all traffic arriving at the opened port from any source to the node that
# requested masquerading.
# The full domain name length may not exceed 253 octets, according to the DNS specification.
# UAVCAN imposes a stricter length limit in order to reduce the memory and traffic burden on the bus: 45 characters.
# 45 characters is the amount of space that is required to represent the longest possible form of an IPv6 address
# (an IPv4-mapped IPv6 address). Examples:
#   "forum.uavcan.org"                              - domain name
#   "192.168.1.1"                                   - IPv4 address
#   "2001:0db8:85a3:0000:0000:8a2e:0370:7334"       - IPv6 address, full form
#   "2001:db8:85a3::8a2e:370:7334"                  - IPv6 address, same as above, short form (preferred)
#   "ABCD:ABCD:ABCD:ABCD:ABCD:ABCD:192.168.158.190" - IPv4-mapped IPv6, full form (length limit, 45 characters)

Another difference that is relevant for DSDL is that padding fields are usually placed directly above the following non-padding field, which leads to undesirable separation of the comment and its field.

Further, the current style (comment before field) requires the data type developer to have awkward gaps between the header comment (which is supposed to apply to the whole data type definition) and the documentation of the first field, as can be seen in this excerpt (the culprit is right above # Modem ...):

#
# It is recommended to use the lowest transport priority level when broadcasting messages of this type,
# in order to avoid interference with a real-time traffic on the bus. Usage of higher priority levels is
# unlikely to be practical because the latency and throughput limitations introduced by the on-board radio
# communication equipment are likely to vastly exceed those of the local CAN bus.
#

# Modem nodes are required to keep the NAT table entries alive for at least this amount of time, unless the
# table is overflowed, in which case they are allowed to remove least recently used entries in favor of
# newer ones. Modem nodes are required to be able to accommodate at least 100 entries in the NAT table.
uint32 NAT_ENTRY_MIN_TTL = 86400        # [second]

If this is not the perfect question for in-depth bikeshedding, I don’t know what is.

  • Comment above field (no change)
  • Comment below field (like Cap’n’Proto)

0 voters

2

Oh no, we’ve failed to reach consensus.

@kjetilkjeka @Zarkopafilis What arguments do we have in favor of keeping the current order unchanged?

3

The biggest part of programming languages and documentation generators, have as a default, the comments to be above the definitions. I’m sticking with this one: I’m used to this, all method / member summaries are displayed this way.

Also, you won’t have to change everything.

4

The biggest part of programming languages and documentation generators, have as a default, the comments to be above the definitions. I’m sticking with this one: I’m used to this, all method / member summaries are displayed this way.

Also, you won’t have to change everything.

+1 to this

When someone versed in the “culture” of coding reads a source file they expect the doc comment to be right before the item it documents.

5

Are there arguments other than historical?

6

@scottdixon let’s hear the opposing side. The question is mildly important right now as I am considering to mention this as a recommended practice in the DSDL spec. I will avoid mentioning this if we fail to agree here.

7

I voted for below because some auto documentation systems, namely python/sphinx, require the documentation to come after the thing they are documenting. I agree with @kjetilkjeka and @Zarkopafilis that supporting documentation generators is important and that most languages do put the docs first. I don’t feel too strongly so I’m fine keeping them above unless we know that this will break some existing autodoc system we wanted to leverage.