在C++中創建公共頭文件時，您認爲最佳實踐是什麼？C/C++頭文件文檔
應該頭文件包含沒有，簡短或大量的文件？我從幾乎沒有任何文檔（依賴於某些外部文檔）到大規格的不變量，有效參數，返回值等等，我已經看到了一切。我不確定我喜歡什麼，大文檔很好，因爲您始終可以訪問另一方面，一個帶有非常簡短文檔的頭文件通常可以在一兩頁文本中顯示一個完整的界面，從而更好地瞭解可能對類進行什麼操作。
比方說，我採用簡短或大量的文檔。我想要類似於javadoc的東西，我在那裏記錄返回值，參數等。在C++中最好的約定是什麼？據我記得，doxygen用java doc樣式的文檔做了很好的事情，但是在使用javadoc樣式文檔之前，還有其他的約定和工具可以幫助我理解嗎？
通常我把文檔界面（參數，返回值，的功能是什麼）在接口文件（.h）中，該文檔在執行落實（函數如何一樣）文件（.c，.cpp，.m）。
我在聲明它之前寫了一個類的概述，所以讀者可以獲得即時的基本信息。
我使用的工具是Doxygen。
我會definetely有一些文件中的頭文件本身。它極大地提高了調試的效率，使代碼旁邊的信息不在單獨的文檔中。作爲一個經驗法則，我會在代碼旁邊記錄API（返回值，參數，狀態更改等）以及單獨文檔中的高級體系結構概述（以更全面地瞭解如何組合所有內容;它是很難將其與代碼一起放置，因爲它通常一次引用多個類）。
Doxygen從我的經驗是好的。
把足夠的代碼放在它可以獨立使用的代碼中。幾乎每個項目我都在文檔分開的地方，它已經過時或沒有完成，部分原因是如果它是一個單獨的文檔，它將成爲一個單獨的任務，部分原因在於管理層不允許它作爲一項任務在預算中。作爲流程的一部分，內聯記錄在我的經驗中效果更好。
以大多數編輯認可的形式編寫文檔是一個塊;對於C++來說，這似乎是/ *而不是//。這樣你就可以摺疊它並看到聲明。
也許你會感興趣gtk-doc。它可以是「有點尷尬的設置和使用」，但你可以從源代碼中一個很好的API文檔，看起來像這樣：
我相信Doxygen的是產生文檔中最常見的平臺，據我所知，它或多或少能夠覆蓋JavaDoc標記（當然不限於此）。我已經使用了doxygen for C，結果不錯，但我確實認爲它更適合C++。你可能也想看看robodoc，雖然我認爲Occam的Razor會告訴你寧願去Doxygen。
關於多少文檔，我從來沒有一個文檔粉絲本人，但我是否喜歡它，有更多的文檔總是跳動沒有文檔。我將API文檔放在頭文件中，並且在實現中使用實現文檔（根據理由，不是嗎？）。 :)這樣，IDE就有機會在autocompletion中顯示它（Eclipse爲JavaDocs執行此操作，例如也可能用於doxygen？），這不應該低估它。 JavaDoc有這個額外的怪癖，它使用第一個句子（即直到第一個句點）作爲一個簡短的描述，不知道Doxygen是否做到這一點，但如果是這樣，在編寫文檔時應該考慮到它。
有很多文檔會冒過時的風險，但是，保持文檔接近代碼將使人們有機會保持最新，所以你應該明確地將它保存在源代碼/頭文件中文件。不應該忘記的是文檔的製作。是的，有些人會直接使用文檔（通過IDE或其他任何方式，或者只是閱讀頭文件），但有些人更喜歡其他方式，因此您應該考慮將您的（定期更新的）API文檔在線，所有內容都很好，可瀏覽，如果你的目標是基於nix的開發者，也許還會生成man文件。
這是我的兩美分。