Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[repository schema] Define documentation purposes and add standard purposes #229

Open
kleihan opened this issue Sep 9, 2024 · 1 comment · May be fixed by #236
Open

[repository schema] Define documentation purposes and add standard purposes #229

kleihan opened this issue Sep 9, 2024 · 1 comment · May be fixed by #236
Assignees
@kleihan
Labels
ERRATA Errors and omissions, inconsistencies

Comments

@kleihan
Copy link
Member

kleihan commented Sep 9, 2024

The schema has an optional attribute purpose for documentation elements and defines a few standard purposes. A user may add to the list as it is extensible.

	<xs:simpleType name="purpose_t">
		<xs:annotation>
			<xs:documentation>Extensible annotation purposes</xs:documentation>
		</xs:annotation>
		<xs:union memberTypes="fixr:purpose_enum xs:string"/>
	</xs:simpleType>

The standard purposes are currently SYNOPSIS, ELABORATION, EXAMPLE, DISPLAY. The specification only lists them but does not offer a definition.

Multiple languages can be supported by specifying the language of each element in its langId attribute. 
Also, multiple categories of documentation are supported by populating the purpose attribute. 
Suggested values of purpose include “SYNOPSIS”, “ELABORATION”, “EXAMPLE”, and “DISPLAY”.

It is proposed to define DISPLAY as the purpose to provide a more elaborate name other than the value of the name attribute, for example (taken from #193):

<fixr:message msgType="F" name="OrderCancelRequest">
  ...
  <fixr:annotation>
    <fixr:documentation purpose="DISPLAY">
      Cancel Order Message (Specifying Order Acceptance Number)</fixr:documentation>
  </fixr:annotation>
</fixr:message>

It is further proposed to standardize the following purposes with clear definitions in the specification:

  • DEFINITION (very short, single line description as opposed to an entire paragraph for SYNOPSIS and multiple paragraphs, lists,... for ELABORATION)
  • CAPTION (as image or figure caption, e.g. for graphical representations of messages, groups, components)
  • TOOLTIP (for GUIs when the mouse hovers over the name of an element)

User-defined purposes should still be allowed but the standard purposes should cover most use cases.
@kleihan kleihan added the ERRATA Errors and omissions, inconsistencies label Sep 9, 2024
@martinswanson
Copy link

martinswanson commented Sep 9, 2024 •
edited
Loading

Generally supportive of adding clearer guidance for the purpose attribute, not least because it simplifies document generation.

Specific notes:

Suggested wording:

Multiple languages can be supported by specifying the language of each element in its langId attribute. Also, multiple categories of documentation are supported by populating the purpose attribute. Suggested values of purpose include “SYNOPSIS”, “ELABORATION”, “EXAMPLE”, “DISPLAY”, “CAPTION”, “TOOLTIP”, and “DEFINITION”.

  • SYNOPSIS: Provides a brief summary of the element, typically highlighting its key function or purpose, restricted to one paragraph for conciseness.
  • ELABORATION: Offers a more detailed explanation of the element, clarifying its usage, functionality, or background.
  • EXAMPLE: Includes a sample or illustration demonstrating how the element is used in practice.
  • DISPLAY: Defines a user-friendly or descriptive name for the element, often used for presentation purposes.
  • CAPTION: Provides a descriptive label or title for the element, often used for headings or brief annotations.
  • TOOLTIP: A short message or hint that appears when hovering over the element, usually explaining its function or use.
  • DEFINITION: Gives a precise and formal explanation of the element, restricted to one sentence in length to ensure brevity.

@kleihan kleihan self-assigned this Sep 9, 2024
This was referenced Sep 11, 2024
Open
Open
@kleihan kleihan linked a pull request Sep 12, 2024 that will close this issue
[#229] Extend recommended documentation purposes and define all purposes #236
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@kleihan kleihan

Labels
ERRATA Errors and omissions, inconsistencies
Projects
Orchestra v1.1 RC2
Status: Backlog
Milestone
No milestone
2 participants
@martinswanson @kleihan