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/) - but I think we could only reasonably enforce it for new code.

Chris

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-guide.html
[2] 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