Review of first draft of D3.5.4_API

MERCEmentre commented 8 years ago

Hello Bernd,

Here is a first review.

All links to modules in §3.2 are broken;
Figures 3 and 4 seem to not be related to the surrounding text. Figure 3 is not commented. Figure 4 is does not match the corresponding text in §3.5.
In §3.6.6, "in" word with nothing behind. Remove it?

Overall, I'm not sure it would be clear to an outsider how the API is really structure. Some suggestions for improvement:

Add explicit links to SCADE model (e.g. the complete path to the SCADE package in model/ directory);
The switching from §3.3 (coming from my own document) to §3.4 (you wrote) might not be clear. Maybe what is missing is a section that describes more precisely the overall structure of "openETCS model run-time" and "openETCS executable model" before diving into interface description. Or just some linking paragraphs to situate §3.4 into the global picture. Or move §3.6 earlier. I don't know.

Sorry for the confusing advices. :-(

I pushed some typo fixes directly to the git repo of the document.

Best regards, david

BerndHekele commented 8 years ago

Hi David, thanks for your advices. I will on my travel back improve the document and try to implement your proposal. kr Bernd

BerndHekele commented 8 years ago

Dear David, I'm coming closer now to the proposed structure. can you please have a second look?

kr Bernd

MERCEmentre commented 8 years ago

Hi Bernd, I'll have a look on Monday.

MERCEmentre commented 8 years ago

Hello Bernd,

I made a new review: it is OK for me right now. I pushed directly to the document the correction of a few typos.

Some remarks/questions:

Regarding the openETCS API, I assume the next step is to integrate the Alstom's API within this document, right?
Regarding the EVC side API: if I remember correctly, only one kind of balise or radio message or other functional input should be given per EVC() call. That should probably be written somewhere in the API document.

Best regards, d.

BerndHekele commented 8 years ago

Dear David, thanks for your support. To answer your questions: yes - we want to give the Alstom API a prominent position with this document - without neglecting the fact there is other ways to do it possible as well. To your second remark - yes - your statement is right and I will check whether it needs to be more precise in the description.

cu Bernd

BerndHekele commented 8 years ago

I added a clarification in section 4.1.3

MERCEmentre commented 8 years ago

It is OK for me. Thanks!

BerndHekele commented 8 years ago

Update is available.

openETCS / modeling

Review of first draft of D3.5.4_API #941