C / C ++头文件的文件 [英] C/C++ Header file documentation

问题描述

创建用C公共头文件时，你怎么认为的最佳实践++？

1. 如果头文件不包含，短暂的或块状的文档？我见过的一切，从几乎没有文档（依靠一些外部文档）大规格不变的，有效的参数，返回值等我不知道到底是什么我preFER，大文件是好的，因为你已经始终可以访问它从你的编辑器，在另一方面具有非常简短的文档，一个头文件往往可以显示文本的一两页给出的可能是怎样的一类做一个更好的概述一个完整的接口。




2. 比方说，我去的东西，如短暂的或块状的文档。我想类似的javadoc，我文档返回值，参数等什么的，在C的最佳惯例++的东西吗？至于我能记得的doxygen对Java文档样式的文档好东西，但还有没有其他约定和工具，在此之前去为的javadoc风格的文档我应该知道的？

解决方案

通常我把文档界面（参数，返回值的什么的功能一样）在接口文件（.H） ，并为执行文件（如何的功能一样）在实现文件（.C，的.cpp，.M）。

我写的类只是其声明之前的概况，让读者有直接的基本信息。

我用的工具是Doxygen的。

What do you think is best practice when creating public header files in C++?

1. Should header files contain no, brief or massive documentation? I've seen everything from almost no documentation (relying on some external documentation) to large specifications of invariants, valid parameters, return values etc. I'm not sure exactly what I prefer, large documentation is nice since you've always access to it from your editor, on the other hand a header file with very brief documentation can often show a complete interface on one or two pages of text giving a much better overview of what's possible to do with a class.

2. Let's say I go with something like brief or massive documentation. I want something similar to javadoc where I document return values, parameters etc. What's the best convention for that in c++? As far as I can remember doxygen does good stuff with java doc-style documentation, but are there any other conventions and tools for this I should be aware of before going for javadoc style documentation?

解决方案

Usually I put documentation for the interface (parameters, return value, what the function does) in the interface file (.h), and the documentation for the implementation (how the function does) in the implementation file (.c, .cpp, .m).

I write an overview of the class just before its declaration, so the reader has immediate basic information.

The tool I use is Doxygen.

这篇关于C / C ++头文件的文件的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！