search

tmtsoftware / icd

ICD - Interface Control Document Management
Other
12 stars 5 forks source link

Render component prefix instead of key #31

Open edwardchapin opened 8 years ago

edwardchapin commented 8 years ago

component-model.conf files define a component key that is generally used as its identifier throughout (e.g., component=oiwfs-adc-assembly), as well as a prefix (e.g., prefix=iris.oiwfs.adc). It is the prefix which is used to address components when using CSW services, rather than the key, so I think it should be the index that is generally rendered in the output (rather than the key, as it is in the current system).

For example, as a programmer, I don't think it's very useful to see that a subsystem subscribes to the telemetry item "oiwfsShift" from the publisher "IRIS.oiwfs-adc-assembly". I would have to click on the "IRIS.oiwfs-adc-assembly" link, and then look at the component definition to see that its prefix is iris.oiwfs.adc.

I suspect it would be fairly trivial to make the following cosmetic changes, which would have the immediate effect of making rendered ICDs more readable:

  1. In the subsystem description table (with columns Subsystem, Name, Prefix, Type, and WBS ID), I would suggest swapping the "Name" and "Prefix" columns, and changing the label "Name" to "key" or something like that (or simply don't render it). This promotes "prefix" to being the more important identifier that we care about.
  2. Every time you need to refer to an external component (e.g., publishers/subscribers for telemetry items, and senders and receivers for commands), render the prefix rather than the key.

(*) 3. In the component selector on the left-hand column, list prefixes rather than keys. I will note that in IRIS we are currently appending the component type to the key (e.g., "1-wire-hcd", and "oiwfs-adc-assembly") to make it easier to identify component types in the selector (which is already getting quite lengthy for IRIS). If/when switching to using prefixes instead, we will not necessarily see the component type in the name (although we are currently giving them prefixes like "iris.hcd.1wire"!). Since this is a UI issue, rather than a rendering issue, perhaps this could be factored out into a separate issue and left until later... e.g., as part of an issue that adds the ability to filter the component selector by component type (assembly/hcd/sequencer).

abrighton commented 8 years ago

Ed: Thanks for the feedback. I will take a look into this when I get back to working on the icd code. Let me know if you have some example ICDs I can test with that use your naming scheme. The longer names might require changes in the web layout.

edwardchapin commented 8 years ago

Allan: Thanks, will do. I have some nearly-ready IRIS and TCS model files that I plan to put into a pull request, but I'm just waiting on the previous (word document) version to be accepted and signed before proceeding. If you need them sooner for testing, just contact me off-line.

abrighton commented 7 years ago

In the latest master branch the PDFs for APIs and ICDs include summary tables at top that display the component's prefix and link to the assembly or HCD detailed view below.

abrighton commented 7 years ago

The latest version displays the publisher, subscriber and prefix.

abrighton commented 5 years ago

Reopening to discuss comment from Ed:

"The issue was closed because the rendering was made clearer, but I am still wondering why there are two parallel naming systems for components when one would suffice (and it would also cause less confusion). For example, for the IRIS POA assembly, I would like to subscribe to the current event published by the IRIS rotator. The way I write this in the POA subscribe-model.conf file is to specify subsystem=IRIS, component=rotator-assembly, name=current. However, the actual name of the event (the thing I subscribe to) is iris.rotator.current, not IRIS.rotator-assembly.current. The component name rotator-assembly is arbitrary, and the only way to know what the correct prefix is is to look at the rotator component-model.conf file for a translation from subsystem+component -> event prefix. Wouldn't it be better if the concepts of component and prefix were combined into one? (and in subscribe-model.conf you just specify the full dot notation of the event you are looking for?) "