genivi-ipc@lists.genivi.org

Development list for inter process communication (IPC) related topics

View all threads

Franca and doxygen documentation

FH
Fabien HERNANDEZ
Fri, Feb 24, 2017 1:33 PM

Hello,

I investigate the joint capacities of Franca and doxygen to generate
documentation.
I'm at a point where I can generate HTML documentation from my fidl file.

I use structured comments to achieve the task:

<**
@description :  sms.fidl
@author : FH
**>

Questions:

  • do we have another way to insert comments (C++ like for example) which
    could be taken into account by doxygen ?
  • it's written in the documentation that @version and @param are
    deprecated, they have some values anyway what is the issue to keep them ?

Problems:

  • when I use the description tag, the result includes a "#comment :" just
    before in the documentation like #comment : sms.fidl
  • the author tag keeps the ":" in front of the name ": FH"

When I look to the output, I have this warning:
/home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment' could
not be resolved

Is it something known ?

I'm using doxygen 1.8.11

Thank you

--

Best regards

Fabien HERNANDEZ
System Architect - Telematic
Valeo Comfort & Driving Assistance Systems

Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47
76, rue Auguste Perret - 94046 Créteil cedex - France

http://www.valeo.com/en/

--

*This e-mail message is intended only for the use of the intended recipient(s).
The information contained therein may be confidential or privileged,
and its disclosure or reproduction is strictly prohibited.
If you are not the intended recipient, please return it immediately to its sender
at the above address and destroy it. *

Hello, I investigate the joint capacities of Franca and doxygen to generate documentation. I'm at a point where I can generate HTML documentation from my fidl file. I use structured comments to achieve the task: <** @description : sms.fidl @author : FH **> Questions: - do we have another way to insert comments (C++ like for example) which could be taken into account by doxygen ? - it's written in the documentation that @version and @param are deprecated, they have some values anyway what is the issue to keep them ? Problems: - when I use the description tag, the result includes a "#comment :" just before in the documentation like #comment : sms.fidl - the author tag keeps the ":" in front of the name ": FH" When I look to the output, I have this warning: /home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment' could not be resolved Is it something known ? I'm using doxygen 1.8.11 Thank you -- Best regards *Fabien HERNANDEZ* System Architect - Telematic Valeo Comfort & Driving Assistance Systems Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47 76, rue Auguste Perret - 94046 Créteil cedex - France <http://www.valeo.com/en/> -- *This e-mail message is intended only for the use of the intended recipient(s). The information contained therein may be confidential or privileged, and its disclosure or reproduction is strictly prohibited. If you are not the intended recipient, please return it immediately to its sender at the above address and destroy it. *
GA
Gunnar Andersson
Mon, Feb 27, 2017 1:45 PM

Answering on your original message to genivi-ipc here.

On Fri, 2017-02-24 at 14:33 +0100, Fabien HERNANDEZ wrote:

Hello,

I investigate the joint capacities of Franca and doxygen to generate
documentation.
I'm at a point where I can generate HTML documentation from my fidl file.

Could you publish a small example?  Your fidl, the run doxygen commands
etc.?  Then it's easier to comment on your result and help.

I use structured comments to achieve the task:

<**
 @description :  sms.fidl
 @author : FH
**>

Are you also getting the actual Franca details appearing in the Doxygen
generated documentation, such as interface name, method name, parameters,
types, ...?

Questions:

  • do we have another way to insert comments (C++ like for example) which
    could be taken into account by doxygen ?

Maybe you have already considered the standard answer for "extra
information" which is the Deployment Model?

I guess the deployment model can contain anything you want more or less.  It
is for most things more powerful to place extended information there and not
in structured comments.  Structured comments create a kind of dialect of
Franca that is unique to you only.  Deployment models might also be unique
sure, but they follow a formal syntax, and this syntax also has a
specification (the deployment specification) provided.  I admit I could also
feel it would be OK to make an exception for Doxygen-style structured
comments for the purpose of documentation only.

But any deployment model goes hand in hand with the code generator that
interprets it, and I assume that is not supported by Doxygen. 
Actually, please enlighten me - what is it exactly that makes Doxygen able
to process Franca in the first place?  How are you doing this?  (again,
example)

  • it's written in the documentation that @version and @param are
    deprecated, they have some values anyway what is the issue to keep them ?

I imagine it is because structured comments are bad in comparison to the
power of the deployment specification, as I noted above.  But I'm sure Klaus
Birken could help to clarify further.

Problems:

  • when I use the description tag, the result includes a "#comment :" just
    before in the documentation like #comment : sms.fidl
  • the author tag keeps the ":" in front of the name ": FH"

When I look to the output, I have this warning:
/home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment'
could not be resolved

Is it something known ?

If these warnings are coming from Doxygen I'm not sure who might know it, or
if anyone else have even tried to do something with Doxygen?

Please start by documenting what you are doing, so that people can add to
it, and then the next time we have a documented body of knowledge around
this.

Thanks,

  • Gunnar

I'm using doxygen 1.8.11

Thank you

-- 

Best regards

Fabien HERNANDEZ
System Architect - Telematic
Valeo Comfort & Driving Assistance Systems

Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47
76, rue Auguste Perret - 94046 Créteil cedex - France

http://www.valeo.com/en/

Answering on your original message to genivi-ipc here. On Fri, 2017-02-24 at 14:33 +0100, Fabien HERNANDEZ wrote: > Hello, > > > I investigate the joint capacities of Franca and doxygen to generate > documentation. > I'm at a point where I can generate HTML documentation from my fidl file. Could you publish a small example? Your fidl, the run doxygen commands etc.? Then it's easier to comment on your result and help. > > I use structured comments to achieve the task: > > <** >  @description :  sms.fidl >  @author : FH > **> Are you also getting the actual Franca details appearing in the Doxygen generated documentation, such as interface name, method name, parameters, types, ...? > > Questions: > - do we have another way to insert comments (C++ like for example) which > could be taken into account by doxygen ? Maybe you have already considered the standard answer for "extra information" which is the Deployment Model? I guess the deployment model can contain anything you want more or less. It is for most things more powerful to place extended information there and not in structured comments.  Structured comments create a kind of dialect of Franca that is unique to you only.  Deployment models might also be unique sure, but they follow a formal syntax, and this syntax also has a specification (the deployment specification) provided.  I admit I could also feel it would be OK to make an exception for Doxygen-style structured comments for the purpose of documentation only. But any deployment model goes hand in hand with the code generator that interprets it, and I assume that is not supported by Doxygen.  Actually, please enlighten me - what is it exactly that makes Doxygen able to process Franca in the first place? How are you doing this? (again, example) > - it's written in the documentation that @version and @param are > deprecated, they have some values anyway what is the issue to keep them ? I imagine it is because structured comments are bad in comparison to the power of the deployment specification, as I noted above. But I'm sure Klaus Birken could help to clarify further. > > Problems: > - when I use the description tag, the result includes a "#comment :" just > before in the documentation like #comment : sms.fidl > - the author tag keeps the ":" in front of the name ": FH" > > When I look to the output, I have this warning: > /home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment' > could not be resolved > > Is it something known ? If these warnings are coming from Doxygen I'm not sure who might know it, or if anyone else have even tried to do something with Doxygen? Please start by documenting what you are doing, so that people can add to it, and then the next time we have a documented body of knowledge around this. Thanks, - Gunnar > > I'm using doxygen 1.8.11 > > > Thank you > > > --  > > Best regards > > > *Fabien HERNANDEZ* > System Architect - Telematic > Valeo Comfort & Driving Assistance Systems > > Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47 > 76, rue Auguste Perret - 94046 Créteil cedex - France > > <http://www.valeo.com/en/> >
FH
Fabien HERNANDEZ
Mon, Feb 27, 2017 5:10 PM

On Mon, Feb 27, 2017 at 2:45 PM, Gunnar Andersson gandersson@genivi.org
wrote:

Answering on your original message to genivi-ipc here.

On Fri, 2017-02-24 at 14:33 +0100, Fabien HERNANDEZ wrote:

Hello,

I investigate the joint capacities of Franca and doxygen to generate
documentation.
I'm at a point where I can generate HTML documentation from my fidl file.

Could you publish a small example?  Your fidl, the run doxygen commands
etc.?  Then it's easier to comment on your result and help.

The fidl file looks like that (a short extract :) :

package cvp.telephony

<**
@author : Fabien Hernandez\n
@description : date - 02/27/2017\n
**>

interface sms {

version {
    major 0
    minor 1
}

<**
    @description : Interfaces provided by the SMS service\n
    @description : version - 0.1\n

    @description : send a SMS according to a destination and a

content)\n
**>
method sendSms {
in {
String destination
SmsTypes.SmsType type
SmsTypes.SmsPayload payload
}
out {
SmsTypes.Status status
}
}

-------- Commands

doxygen TelematicPlatform.doxyconf

specific values in the doxyconf file:
EXTENSION_MAPPING      = fidl=IDL
FILTER_PATTERNS        = *.fidl=/home/dev/adk/doc/Franca2IDLFilter.sh

The script is (the jar is provided with Franca tools) :
#!/bin/sh
java -jar Franca2IDL.jar -f $1

I use structured comments to achieve the task:

<**
@description :  sms.fidl
@author : FH
**>

Are you also getting the actual Franca details appearing in the Doxygen
generated documentation, such as interface name, method name, parameters,
types, ...?

Only author and descriptions tags + interface names and methods are visible
(parameters are visible but only in the context if the prototype
because the @param is not valid).

For the previous fidl, I got (inside the data structure hierarchy):

void cvp::telephony::sms::sendSms ( in String  destination,
in SmsType  type,
in SmsPayload  payload,
out Status  status
)

Questions:

  • do we have another way to insert comments (C++ like for example) which
    could be taken into account by doxygen ?

Maybe you have already considered the standard answer for "extra
information" which is the Deployment Model?

I guess the deployment model can contain anything you want more or less.
It
is for most things more powerful to place extended information there and
not
in structured comments.  Structured comments create a kind of dialect of
Franca that is unique to you only.  Deployment models might also be unique
sure, but they follow a formal syntax, and this syntax also has a
specification (the deployment specification) provided.  I admit I could
also
feel it would be OK to make an exception for Doxygen-style structured
comments for the purpose of documentation only.

But any deployment model goes hand in hand with the code generator that
interprets it, and I assume that is not supported by Doxygen.
Actually, please enlighten me - what is it exactly that makes Doxygen able
to process Franca in the first place?  How are you doing this?  (again,
example)

You need to transform the fidl file into IDL to get back on standard model
(the FRANCA2IDL filter) and then process with doxygen

  • it's written in the documentation that @version and @param are
    deprecated, they have some values anyway what is the issue to keep them ?

I imagine it is because structured comments are bad in comparison to the
power of the deployment specification, as I noted above.  But I'm sure
Klaus
Birken could help to clarify further.

Problems:

  • when I use the description tag, the result includes a "#comment :" just
    before in the documentation like #comment : sms.fidl
  • the author tag keeps the ":" in front of the name ": FH"

When I look to the output, I have this warning:
/home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment'
could not be resolved

Is it something known ?

If these warnings are coming from Doxygen I'm not sure who might know it,
or
if anyone else have even tried to do something with Doxygen?

Please start by documenting what you are doing, so that people can add to
it, and then the next time we have a documented body of knowledge around
this.

Thanks,

  • Gunnar

Finally, there're rationales behind the restriction. Let see how I can get
ride of
them ....

I'm using doxygen 1.8.11

Thank you

--

Best regards

Fabien HERNANDEZ
System Architect - Telematic
Valeo Comfort & Driving Assistance Systems

Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47
76, rue Auguste Perret - 94046 Créteil cedex - France

http://www.valeo.com/en/

--

Best regards

Fabien HERNANDEZ
System Architect - Telematic
Valeo Comfort & Driving Assistance Systems

Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47
76, rue Auguste Perret - 94046 Créteil cedex - France

http://www.valeo.com/en/

--

*This e-mail message is intended only for the use of the intended recipient(s).
The information contained therein may be confidential or privileged,
and its disclosure or reproduction is strictly prohibited.
If you are not the intended recipient, please return it immediately to its sender
at the above address and destroy it. *

On Mon, Feb 27, 2017 at 2:45 PM, Gunnar Andersson <gandersson@genivi.org> wrote: > > Answering on your original message to genivi-ipc here. > > On Fri, 2017-02-24 at 14:33 +0100, Fabien HERNANDEZ wrote: > > Hello, > > > > > > I investigate the joint capacities of Franca and doxygen to generate > > documentation. > > I'm at a point where I can generate HTML documentation from my fidl file. > > Could you publish a small example? Your fidl, the run doxygen commands > etc.? Then it's easier to comment on your result and help. > > The fidl file looks like that (a short extract :) : package cvp.telephony <** @author : Fabien Hernandez\n @description : date - 02/27/2017\n **> interface sms { version { major 0 minor 1 } <** @description : Interfaces provided by the SMS service\n @description : version - 0.1\n @description : send a SMS according to a destination and a content)\n **> method sendSms { in { String destination SmsTypes.SmsType type SmsTypes.SmsPayload payload } out { SmsTypes.Status status } } -------- Commands doxygen TelematicPlatform.doxyconf specific values in the doxyconf file: EXTENSION_MAPPING = fidl=IDL FILTER_PATTERNS = *.fidl=/home/dev/adk/doc/Franca2IDLFilter.sh The script is (the jar is provided with Franca tools) : #!/bin/sh java -jar Franca2IDL.jar -f $1 > > > I use structured comments to achieve the task: > > > > <** > > @description : sms.fidl > > @author : FH > > **> > > Are you also getting the actual Franca details appearing in the Doxygen > generated documentation, such as interface name, method name, parameters, > types, ...? > > Only author and descriptions tags + interface names and methods are visible (parameters are visible but only in the context if the prototype because the @param is not valid). For the previous fidl, I got (inside the data structure hierarchy): void cvp::telephony::sms::sendSms ( in String *destination*, in SmsType *type*, in SmsPayload *payload*, out Status *status* ) > > > > Questions: > > - do we have another way to insert comments (C++ like for example) which > > could be taken into account by doxygen ? > > Maybe you have already considered the standard answer for "extra > information" which is the Deployment Model? > > I guess the deployment model can contain anything you want more or less. > It > is for most things more powerful to place extended information there and > not > in structured comments. Structured comments create a kind of dialect of > Franca that is unique to you only. Deployment models might also be unique > sure, but they follow a formal syntax, and this syntax also has a > specification (the deployment specification) provided. I admit I could > also > feel it would be OK to make an exception for Doxygen-style structured > comments for the purpose of documentation only. > > But any deployment model goes hand in hand with the code generator that > interprets it, and I assume that is not supported by Doxygen. > Actually, please enlighten me - what is it exactly that makes Doxygen able > to process Franca in the first place? How are you doing this? (again, > example) > You need to transform the fidl file into IDL to get back on standard model (the FRANCA2IDL filter) and then process with doxygen > > > - it's written in the documentation that @version and @param are > > deprecated, they have some values anyway what is the issue to keep them ? > > I imagine it is because structured comments are bad in comparison to the > power of the deployment specification, as I noted above. But I'm sure > Klaus > Birken could help to clarify further. > > > > > Problems: > > - when I use the description tag, the result includes a "#comment :" just > > before in the documentation like #comment : sms.fidl > > - the author tag keeps the ":" in front of the name ": FH" > > > > When I look to the output, I have this warning: > > /home/dev/adk/sms.fidl:2: warning: explicit link request to 'comment' > > could not be resolved > > > > Is it something known ? > > If these warnings are coming from Doxygen I'm not sure who might know it, > or > if anyone else have even tried to do something with Doxygen? > > Please start by documenting what you are doing, so that people can add to > it, and then the next time we have a documented body of knowledge around > this. > > Thanks, > - Gunnar > > Finally, there're rationales behind the restriction. Let see how I can get ride of them .... > > > > > I'm using doxygen 1.8.11 > > > > > > Thank you > > > > > > -- > > > > Best regards > > > > > > *Fabien HERNANDEZ* > > System Architect - Telematic > > Valeo Comfort & Driving Assistance Systems > > > > Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47 > > 76, rue Auguste Perret - 94046 Créteil cedex - France > > > > <http://www.valeo.com/en/> > > > > -- Best regards *Fabien HERNANDEZ* System Architect - Telematic Valeo Comfort & Driving Assistance Systems Tel: (+33) 1 48 84 54 94 / Cell: (+33) 7 60 59 66 47 76, rue Auguste Perret - 94046 Créteil cedex - France <http://www.valeo.com/en/> -- *This e-mail message is intended only for the use of the intended recipient(s). The information contained therein may be confidential or privileged, and its disclosure or reproduction is strictly prohibited. If you are not the intended recipient, please return it immediately to its sender at the above address and destroy it. *