Click here to Skip to main content
15,877,859 members
Please Sign up or sign in to vote.
1.00/5 (1 vote)
See more:
The basic issue is that there is but so much screen width and height, and as a class gets more complicated, it is difficult to plan everything out. DOxygen might work to some extent to document the process.

At one point I had proposed that Wordpress could be used for such a task
[1]. However, in a Windows 7 ultimate environment, or online, that gives two options: either either make everything public or have a local solution. If it is Word-press base, there can be complications with the installation that temporarily make that not feasible.

For now, I am looking at a plain HTML solution. HTML can reference multiple directory levels. I tried using Open Office to save the HTML file, but there are formatting issues with the output.

-So the temporary workaround for now is to use the online quackit Online HTML Editor to generate the HTML with tables that document each level of the CCDCDirectControls class (it is nested, so there are multiple levels, that can be placed in sub-directories referenced as HTML links) Online HTML Editor - Full[2]. And then I can use Notepad++ Notepad++ v6.8.8 - Current Version[3] to save the documentation locally.

I can start documenting in a table what the current status is for the different sub-class portions that need to be coded, and there status, whether they are declared in the header, defined in the header with TODO code, or fully defined in the C++ code.

As an example that I liked previously, there is the C++ online documentation for the Magick++ that could easily have been written (at least at top levels) before coding as well as updated during coding or after http://www.imagemagick.org/Magick++/Documentation.html[4].

Or is there a better option? What is recommended to make easily-readable documentation to follow during the coding process (before-hand, updating during, and then for reference after)?

I heard something about markup being good, but when I searched for it, I found dOxygen which seemed perhaps better for after-the-fact that the code was done rather than planning before hand. Does anyone know more about this approach?
Posted

1 solution

My tip is to rely on DOxygen, because it is an industry leading tool. Code documentation is an annoying issue which nobody likes, and so it often lacks or even fails. Because code is developing over some years you need a simple tools which makes little work.

Another approach can be inheritance. Make the public stuff WITH documentation and inherite a protected class which got no documentation.

Nested classes I would really avoid. If you wanted some clearance use namespace declarations.
 
Share this answer
 
Comments
StephenJElliott 3-Feb-16 5:17am    
Thank you for your solution... I tried DOxygen; it really was not so useful the way it turned out for me, as a design tool. As for namespace declarations they are very similar to nested classes - except the namespace I guess might be able to span multiple file, so scoping is a mess; probably anonymous namespace is the best; For really complicated programs, I am still set on nested classes to described the hereditary structure properly.

Just to mention also that there can be an include file #include subclassexample.h within a nested class (which seems really complicated, but it allows one to extend the hierarchy if needed even further to keep the encapsulation clean).

This issue is actually a core issue for me. I have workarounds, but this is really what I need to solve right now. Further suggestions are appreciated.

This content, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)



CodeProject, 20 Bay Street, 11th Floor Toronto, Ontario, Canada M5J 2N8 +1 (416) 849-8900