CWL: Comments in Common Workflow Language

Question

[kevin.o.oluoch]

I have a couple of questions about comments or documenting in CWL.

1a. What is the difference between 'doc' and 'label' in CWL?

1b. What are the special cases in which one is better than the other?

2a. Are line that start with hash tags, also comments?

2b. if no, what is the use of hash tags? if yes, whats the difference between a hash tag, 'doc' and 'label'?

Answer 1

[Michael R. Crusoe]

Hello kevin.o.oluoch and thank you for your question.

1a:

From http://www.commonwl.org/v1.0/CommandLineTool.html#CommandLineTool we learn that

label […] A short, human-readable label of this process object.

and

doc […] A long, human-readable description of this process object.

1b. doc is really for longer documentation, possible several paragraphs. label shouldn't be more than a sentence (if not just a fragment)

2a. hash tags (YAML comments) are comments visible only to viewers of the raw CWL description. They don't get represented in the data model.

Example: https://github.com/ProteinsWebTeam/ebi-metagenomics-cwl/blob/ca6ca61/tools/FragGeneScan1_20.cwl#L35

inputs:
  sequence:
    type: File
    format: edam:format_1929  # FASTA

2b. I personally use the in line comments to leave notes for myself and others who are editing or reading the raw CWL description.

I hope you found this explanation helpful!

[kevin.o.oluoch]

Thanks a lot I was getting confused especially with hash tags. I guess this will be helpful to many people who may have noticed the use of the three types of comments.