2
\$\begingroup\$

How should an entity and an architecture be commented in VHDL to best be used with Doxygen?

Im trying to use Doxygen to generate useful documentation for my VHDL, but im not sure of the best way to comment what where.

  1. Should entity be commented to describe every signal, their size, their function, their type? Or as a black box?
  2. Should architecture be commented as a black box? Something going in, something coming out? Or should each (mentionable) line be summed up?
  3. Should the architecture and entity have the same description?
  4. How about 3. if I have several architectures using the same entity?

For all I can see doxygen ignores comments inside architectures so for 2. this should possibly be taken into account?

\$\endgroup\$

1 Answer 1

2
\$\begingroup\$

In VHDL and in everything, there is never too many comments. Comments save a lot of time when somebdy else needs to continue your work, or interface it, or just understand it. Thus, each entity, signal and process needs to be explained.

There are also others convention, such as naming and make your code as clear as possible by indenting, align the entity port etc.

[EDIT]

You need to explain the entire module (entity + architecture) : what is it for, how does it work, how does it interface with other modules. Then you can specify the program developement unit, file, device, and autor of the module. You can inlcude an history, and what Tools do you use for simulation, synthesis, routing, how long should you simulate.

For the entity you explain what is it for and how does it work.

\$\endgroup\$
1
  • \$\begingroup\$ The question is more what should be said about an architecture, and what about an entity. My code is widely commented and I would say all the variable are named sensibly, but it is not clear what is expected to comment before the architecture and entity. \$\endgroup\$ Mar 21, 2017 at 16:06

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.