Display in/out contracts

[zopsicle]

doc2 inserts the in/out contracts in HTML. However, CSS causes them to be hidden. Is there a reason for this? I think it would be nice to show the contracts since they are part of the API.

adrdox/style.css

Lines 581 to 585 in e1c1c72

	.function-prototype .in-contract,
	.function-prototype .out-contract {
	display: none;
	white-space: pre;
	}

[adamdruppe]

On Sun, Jun 16, 2019 at 06:32:23AM -0700, Chloé Kekoa wrote: doc2 inserts the in/out contracts in HTML. However, CSS causes them to be hidden. Is there a reason for this? I think it would be nice to show the contracts since they are part of the API.

Yeah, I have just found it mostly to be unhelpful; a lot of these contracts aren't written with the intention of being legible as documentation. It works sometimes, but for a lot of code it ended up just being useless clutter. I keep it here because I'd really like it to work. Maybe it should just be moved somewhere else on the page, or reformatted or something.

[zopsicle]

Perhaps display: none; could be removed, and the person that invokes doc2 could give a command-line flag if they want contracts to be included?

[adamdruppe]

On Sun, Jun 16, 2019 at 06:39:53AM -0700, Chloé Kekoa wrote: Perhaps `display: none;` could be removed, and the person that invokes doc2 could give a command-line flag if they want contracts to be included?

That might work, though I prefer to get it working for everyone if we can to have sensible defaults. Do you think it works where it is now in the html, along with the rest of the prototype? Or maybe would it be better if I moved it to a different section?

[zopsicle]

I'm indifferent. I suppose listing them under headers Preconditions and Postconditions headers would be nice.

Perhaps the programmer could further clarify them if they write their own Preconditions and Postconditions headers (make them special like Throws, See_Also, etc).

/**
 * Does a foo.
 *
 * Preconditions:
 *
 * x must not be negative because bla.
 */
void foo(int x)
in (x >= 0)
{ ... }

Does a foo.

void foo(int x)

Preconditions

x must not be negative because bla.

in (x >= 0)

[adamdruppe]

On Sun, Jun 16, 2019 at 11:32:31AM -0700, Chloé Kekoa wrote: I'm indifferent. I suppose listing them under headers _Preconditions_ and _Postconditions_ headers would be nice.

Perhaps. BTW for your own use, of course you can just delete the line from the css file. But I think I like having it as headers.