c++ - Dual purpose code commenting(users & maintainers)...HOW? -

-

i writing c++ static library , have been commenting doxygen comments in implementation files. have never had care documentation working on needs documented users , trying replace previous bad habit of wanting code , not document better software engineering practices.

anyway, realized other day need couple different types of documentation, 1 type users of library(doxygen manual) , comments myself or future maintainer deal more implementation details.

one of solutions put doxygen comments file, class, , methods @ bottom of implementation file. there out of way , include normal comments in/around method definitions benefit programmer. know it's more work seems best way me achieve 2 separate types of commenting/documentation. agree or have solutions/principles might helpful. looked around site couldn't find threads dealt this.

also, don't want litter interface file comments because feel it's better let interface speak itself. rather manual place user can if need deeper understanding of library interface. on right track here?

any thoughts or comments appreciated.

edit: comments. have learned alot hearing them. think have better uderstanding of how go separating user manual code comments useful maintainer. idea @jalf has having "prose" style manual helps explain how use library. think better reference manual. being said...i feel reference manual might come in handy. think combine advice thoughts of others , try create hybrid.(a prose manual(using doxygen tags page, section, subsection) links reference manual.) suggestion liked @jalf idea of code not having whole manual interleaved it. can avoid placing of doxygen comments @ bottom of implementation file. leaves headers clean , implementation clean place comments useful maintaining implementation. see if works out in reality. these thoughts on have learned far. not positive approach going work or practical. time tell.

i believe comments users should not inline in code, doxygen comments or that. should separate document, in prose form. user of library, don't need to, or want to, know each parameter function means. hopefully, that's obvious. need know function does. , need know why , when call it. , need know pre- , postconditions apply. assumptions function make when call it, , guarantees provide when returns?

library users don't need comments, need documentation. describe how library structured , how works , how use it, , outside code, in actual text document.

of course, code may still contain comments directed @ maintainers, explaining why implementation looks way does, or how works if it's not obvious. documentation library user needs should not in code.


Comments

Post a Comment

Popular posts from this blog

c++ - Convert big endian to little endian when reading from a binary file -

-
this question has answer here: how convert between big-endian , little-endian values in c++? 28 answers i've been looking around how convert big-endian little-endians. didn't find solve problem. seem there's many way can conversion. anyway following code works ok in big-endian system. how should write conversion function work on little-endian system well? this homework, since systems @ school running big-endian system. it's got curious , wanted make work on home computer also #include <iostream> #include <fstream> using namespace std; int main() { ifstream file; file.open("file.bin", ios::in | ios::binary); if(!file) cerr << "not able read" << endl; else { cout << "opened" << endl; int i_var; double d_var; while(!file.eof()) {...
Read more

gdi+ - WxWidgets draw a bitmap with opacity -

-
how can draw wximage, or wxbitmap dc opacity? looks not possible standard dc or wxgraphicscontext. beginlayer/endlayer not yet implemented in wxgraphicscontext have been 1 solution. gdi+ doesn't seem support layers, non-trivial add this. the solution seems to programmatically alter alpha channel pixel-by-pixel? void yourcustomwindow::onpaint( wxpaintevent& event ) { wxpaintdc dc(this); wximage image( width, height ); image.initalpha(); unsigned char* imgdata = img.getdata(); unsigned char* imgalpha = img.getalpha(); // manipulate raw memory buffers populate // them whatever image like. // putting zeros everywhere create // transparent image. // done, not quite... // wxdc can draw wxbitmaps, not wximage, // 1 last step required // wxbitmap bmp( image ); dc.drawbitmap( bmp, 0, 0 ); }
Read more

C#: Application without a window or taskbar item (background app) that can still use Console.WriteLine() -

-
i'm trying create application adheres following: no taskbar no console or form window can utilize console.writeline() . (i.e. if executes app command prompt write console.) the problem if create windows form (or wpf) application can have there no taskbar, console or window show up, console.writeline() nothing. if create console app, writes console, can't figure out how hide (and if did hide it, write command prompt window?)... how do this? just create standard console application. callers responsibility hide window caused program (from how run c# console application console hidden ): system.diagnostics.processstartinfo start = new system.diagnostics.processstartinfo(); start.filename = dir + @"\myprocesstostart.exe"; start.windowstyle = system.diagnostics.processwindowstyle.hidden;
Read more