add section to each API description that enumerates and describes each parameter and the returned value/semantics.

[Max Grossman]

Right now, one large difference between the UPC++ specification and other open communication library specifications (e.g. MPI, OpenSHMEM) is that there is no dedicated section in each API listing that describes the meaning/semantics of each argument and of the returned value (if any).

This is a bit of an oversight, given that the UPC++ specification is more explicit/clear in some areas that the others overlook (e.g. progress model, C++ memory model).

I would support adding this content to each API listing (possibly incrementally, so that effort vs. reward function isn’t a step function).

[Dan Bonachea]

@Max Grossman : Thanks for the feedback. I think I understand what you are suggesting, but can you give an example of a function where this would fix an ambiguity or provide a significant improvement in clarity? (ie more than just stylistic preference)

The general approach we've taken in the spec is to avoid pointless repetition of information, because it increases maintenance cost and saying the same thing in multiple places just introduces the potential for semantic divergence (which could result in more harm than good).

I find that most of our argument names are self-explanatory - ie for readers familiar with the function semantics, the argument type and name are sufficient to get the call right. Those unfamiliar with the semantics will obviously need to read the semantics regardless, so explaining the arguments in isolation is just redundant.

[Max Grossman]

@Dan Bonachea I agree in principle, but I do think that having a table that outlines the semantics for each argument and the return value adds a bit of structure and rigor to the spec. Given a perfectly written API description, the table I’m proposing would be 100% redundant. But I think it also has value in forcing anyone adding to the spec to write out precise descriptions for each entity’s semantics. That would theoretically include things like IN, OUT, or IN/OUT for arguments, which would have eliminated Sayan and my confusion on the semantics of the value argument to reduce_all.

I’m not necessarily disagreeing with your point, I just think that it’s often easy to overlook all the ways in which an API description can be vague so having a form to fill in where possible can help. I’m assuming this is why MPI and SHMEM do it this way as well.

[Dan Bonachea]

This was discussed in the 2020-02-12 meeting and deferred to next release milestone.

[Dan Bonachea]

Mass roll-over of open issues to next release milestone

[Dan Bonachea]

Mass roll-over of open issues to next release milestone

[Amir Kamil]

This was discussed in the 2021-04-17 Pagoda meeting.

We decided that the value of such a change does not justify the overhead of making it and maintaining the resulting sections, so we won't pursue it.