PDF: support document description in request header

[chgeo]

Add DocumentDescriptionLocation to support this scenario.

Also, make DocumentDescriptionReference and DocumentDescriptionCollection optional.

[cla-assistant]

All committers have signed the CLA.

[chgeo]

Not sure here if value 0 is correct. Would rather like to read it entitySet.

[HerzogIgzorn]

If this points to an enum, don't we need a value help for it?

[chgeo]

I haven't seen value helps in the other documents either, so would guess this is not a use case here.

For concrete DocumentDescription... properties, they are not user-facing, but only filled programmatically. One application, for example, will set DocumentDescriptionLocation to header, the other will set it to entitySet. But it's not the user that decides it.

[HeikoTheissen]

Avoid property DocumentDescriptionLocation

[HeikoTheissen]

Suggested change

<Property Name="DocumentDescriptionLocation" Type="PDF.DocumentDescriptionLocation" DefaultValue="0">

[HeikoTheissen]

Suggested change

	<Property Name="DocumentDescriptionCollection" Type="Edm.String">
	<Annotation Term="Core.Description" String="Name of entity set containing the DocumentDescription" />
	</Property>
	<Property Name="DocumentDescriptionCollection" Type="Edm.String">
	<Annotation Term="Core.Description" String="Name of entity set containing the DocumentDescription" />
	<Annotation Term="Core.LongDescription">
	<String>If this is null, the request header 'SAP-Document-Description' must contain the base64-encoded JSON string of the document description.</String>
	</Annotation>
	</Property>

[HeikoTheissen]

Suggested change

	<EnumType Name="DocumentDescriptionLocation">
	<Member Name="entitySet" Value="0">
	<Annotation Term="Core.Description" String="Document description is given as entity set" />
	</Member>
	<Member Name="header" Value="1">
	<Annotation Term="Core.Description" String="Document description is given in a request header" />
	</Member>
	</EnumType>

[chgeo]

Avoid property DocumentDescriptionLocation

Maybe I missed your point, but what do you mean by 'avoid DocumentDescriptionLocation'? It's the very thing I wanted to introduce.

[HeikoTheissen]

Avoid property DocumentDescriptionLocation

Maybe I missed your point, but what do you mean by 'avoid DocumentDescriptionLocation'? It's the very thing I wanted to introduce.

I think we don't need it if we simply state

If DocumentDescriptionCollection is null, the request header 'SAP-Document-Description' must contain the base64-encoded JSON string of the document description.

[fb0d3nheimer]

I think we don't need it if we simply state

This is too implicit. We need an explicit parameter for clean design. According to our architect.

[HeikoTheissen]

This is too implicit. We need an explicit parameter for clean design. According to our architect.

I consider such dependencies between different properties unclean. Better have one complex type FeaturesHeaderType without DocumentDescriptionReference and DocumentDescriptionCollection and a derived complex type FeaturesEntitySetType that includes them (non-nullable). By choosing one of these two types, the annotation declares whether the document description is in the header or in the entity set.