Hi Chris, +David
I think it would be good to make a call on it. Because then we can cleanup at least our platform. If you say it is doxygen I expect there is any tool which can be used for checking. If it is something else that's fine too.
I just want to open this topic to be able to fix our code in a way how it should be.
Thanks, Michal
On 4/3/23 14:13, Chris Kay wrote:
Sorry, I sent my response just as Sandrine did so I'll re-submit it here for the sake of thread continuity:
Hi Michal,
TF-A doesn't currently employ any source-level documentation tool so the documentation style varies across the code-base and we don't enforce any particular style. Doxygen is something that we might want to consider - particularly because it can be integrated directly into the existing Sphinx documentation via Breathe (https://breathe.readthedocs.io/en/latest/ https://breathe.readthedocs.io/en/latest/) - but I think we could only reasonably enforce it for new code.
Chris
*From:* Sandrine Bailleux via TF-A tf-a@lists.trustedfirmware.org *Sent:* 03 April 2023 13:11 *To:* Michal Simek monstr@monstr.eu; tf-a@lists.trustedfirmware.org tf-a@lists.trustedfirmware.org *Subject:* [TF-A] Re: TF-A code documentation Hi Michal,
Thanks for starting this thread. I'll give my own opinion on this topic.
I think there are areas that could benefit from such documentation generation techniques. A prime example would be the porting guide [1]. I would be favorable to the adoption of some Doxygen-like tool (exact tool TBD) for documenting platform interfaces and auto-generate the porting guide from that.
Maybe generic drivers (GPT, console, I/O, ...) would be good candidates too.
But I would not generalize Doxygen-like comments across the entire code base. This sounds too heavyweight on developers to me with no obvious gain.
Also I think this would not replace design documents [2], only complement them. Not saying you're suggesting to replace them! but I just wanted to point it out.
Regards, Sandrine
[1] https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/porting-g... https://trustedfirmware-a.readthedocs.io/en/latest/getting_started/porting-guide.html [2] https://trustedfirmware-a.readthedocs.io/en/latest/components/index.html https://trustedfirmware-a.readthedocs.io/en/latest/components/index.html
On 4/3/23 13:37, Michal Simek via TF-A wrote:
Hi,
I have talked to a couple of people to figure out what TF-A project is using for code documentation. Because I see at least in our platform that our documentation is somewhere between doxygen and kernel-doc but actually with a lot of mismatches. Sanbrine mentioned sending an email to the mailing list to start to have discussion about it.
That's why I want to know the official code documentation format and how we should be checking that everything matches to make sure that documentation is not out of sync from code itself. When this is clear I will ask my team to fix all these issues.
Thanks, Michal
-- TF-A mailing list -- tf-a@lists.trustedfirmware.org To unsubscribe send an email to tf-a-leave@lists.trustedfirmware.org