Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 5 years ago.
Improve this question
I'm working on a fairly big open source RTS game engine (Spring). I recently added a bunch of new C++ functions callable by Lua, and am wondering how to best document them, and at the same time also stimulate people to write/update documentation for a lot of existing Lua call-outs.
So I figured it may be nice if I could write the documentation initially as doxygen comments near the C++ functions - this is easy because the function body obviously defines exactly what the function does. However, I would like the documentation to be improved by game developers using the engine, who generally have little understanding of git (the VCS we use) or C++.
Hence, it would be ideal if there was a way to automatically generate apidocs from the C++ file, but also to have a wiki-like web interface to allow a much wider audience to update the comments, add examples, etc.
So I'm wondering, does there exist a web tool which integrates doxygen style formatting, wiki-like editing for those comments (preferably without allowing editing any other parts of the source file) and git? (to commit the comments changed through the web interface to a special branch)
We developers could then merge this branch every now and then to add the improvements to the master branch, and at the same time any improvements by developers to the documentation would end up on this web tool with just a merge of the master branch into this special branch.
I haven't found anything yet, doubt something this specific exists yet, so any suggestions are welcome!
This is a very cool idea indeed, and a couple of years ago I also had a very strong need for something like that. Unfortunately, at least back then, I wasn't able to find something like that. Doing a quick search on sourceforge and freshmeat also doesn't bring up anything related today.
But I agree that such a wiki frontend to user-contributed documentation would be very useful, I know for a fact that something like this was recently being discussed also within the Lua community (see this).
So, maybe we can determine the requirements in order to come up with a basic working draft/prototype?
Hopefully, this would get us going to initiate such a project with a minimum set of features and then simply release it into the wild as an open source project (e.g. on sourceforge), so that other users can contribute to it.
Ideally, one could use unified patches to apply changes that were contributed in such a fashion. Also, it would probably make sense to restrict modifications only to adding/editing comments, instead of allowing arbitrary modifications of text, this could probably be implemented by using a simple regex.
Maybe, one could implement something like that by modifying an existing (established) wiki software such as mediawiki. Or preferably something that's already using git as a backend for storage purposes. Then, one would mainly need to cater for those Doxygen-style comments, and provide a simple interface on top of it.
Thinking about it some more, DoxyGen itself already provides support for generating HTML documentation, so from that perspective it might actually be interesting to see, how DoxyGen could possibly be extended, so that it is well integrated with such a scripted backend that allows for easy customization of embedded source code documentation.
This would probably mainly boil down to providing a standalone script with doxygen (e.g. in python, php or perl) and then optionally embed forms in the automatically created HTML documentation, so that documentation fixes/augmentations can be sent to the corresponding script via a browser, which in turn would write any modifications back to a corresponding branch.
In the long term, it would be cool if such a script would support different types of backends (CVS, SVN or git), or at least be implemented generically enough, so that it is easily extendible.
So, if we can come up with a good design, it might even be possible that such a modification would be generally accepted as a contribution to doxygen itself, which would also give the whole thing much more exposure and momentum.
Even if the idea doesn't directly materialize into a real project, it would be interesting to see how many other users actually like the idea, so that it could possibly be mentioned in the doxygen issue tracker (https://github.com/doxygen/doxygen/issues/new).
EDIT: You may also want to check out this article titled "Documentation, Git and MediaWiki".
Related
Closed. This question needs to be more focused. It is not currently accepting answers.
Want to improve this question? Update the question so it focuses on one problem only by editing this post.
Closed 1 year ago.
Improve this question
I'm working on a project that I want to publish on GitHub. This project requires a specific algorithm Algorithm. Every project I have worked on previously has only used my code (plus STL, etc.), but Algorithm can be a pain in the butt to write, so I want to use someone else's. Algorithm is a small subroutine compared to the size of the rest of my code.
I find a GitHub repository that implements Algorithm, but there is a lot of Junk. By Junk, I mean code I don't need. I want to strip away all the Junk from Algorithm and use it, but I'm not sure how to do that. Ideally, Algorithm could be cleaned off and placed seamlessly within my project directory to reduce dependencies for other users of my project.
I don't know the etiquette for using someone else's code. I don't know how to give credit or what the deal is with all these licenses.
It appears to me that I have five options for how to use someone else's implementation of Algorithm.
include the original header that declares Algorithm and all the Junk that comes with it. (Do I copy the header and all of its dependencies into my project directory?)
Create a new header and source file that keeps the implementation Algorithm as-is with all comments and #include the header into my project (leaving out additional functions and classes that may have appeared in the original header).
Modify the code implementing Algorithm to remove the remaining Junk. Remove comments. Change C arrays to std::vectors. Replace pointers with smart pointers. Change thrown exceptions. Remove "options" that my project doesn't need. Change the representation of data to merge everything with my project.
Rewrite Algorithm from scratch, but model it after the existing code, conforming the implementation to my style and making minor performance improvements (nothing that is worth pulling onto the existing repository, however).
What are the rules of etiquette for each of the 4 situations? Where do I put the Algorithm within the project directory? How do I credit someone else's work? How do I credit someone for their modified work (that, for example, removes their original comments)? How do I avoid crediting someone else for work I did (that they may think, hypothetically, uses bad coding practices)? What GitHub features facilitate all this?
Regarding licenses, if using someone's Algorithm to get my code running forces me to publish it with a specific license, can I later implement my own Algorithm and change the licencing? I don't know if I will care to do that, but it would be nice to know.
In general, when a developer releases code on Github under a specific license, they expect the code to be taken and used elsewhere in accordance to this license. There is no additional burden on you to appease the developer in any way except following the license.
MPL2 is very open to taking the code and incorporating it in another project even of a different license, as long as the licensed file itself (and any changes you make to it) stays licensed under MPL2. MIT license is even more permissive, here you can relicense as you see fit. Note that you still need to follow the attribution clause, citing MIT licence:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
So just keep this header intact. For MPL2 see the FAQ.
If you later choose to remove the code from your project and reimplement the same logic in a clean way, the copyrighted code is gone and so are the license terms.
Now to the best practices:
If you don't see a need for bigger changes in the code, and it doesn't come with lots of baggage, you would include it (mostly) untouched, which gives you the advantage of being able to upgrade the code easily later on. Expect the original implementation to move on, especially regarding bug fixes. Try to profit from them by staying close to the original instead of ending up with a bunch of code that you now have to maintain yourself.
If you have substantial, general improvements to the code in mind, e.g. modernization as you mentioned, consider to give them back in form of a pull request. For this, again, you need to keep the overall structure of the original code intact so the pull request will indeed only contain these improvements. The original author now may choose to benefit from your improvements or not. If they do, we get back to point 1: even while you did significant changes to the code, you can still profit from maintenance by the original author.
If there is a lot of junk involved that is unnecessary to your project and that you feel is a maintenance burden or comes with additional dependencies, or if your changes are both significant and specific to your own implementation so you don't see them being helpful to the original author (or generally see the chances of a successful pull request being slim) then just bite the bullet and fully assimilate the code. This is also the best option when the original project appears 'dead', e.g. no significant commit activity in ages etc.
Obviously there is no general rule as of what option is best so this is supposed to merely guide you with the decision.
Note that there is also a technical consideration of "how" to adopt the code. It may be beneficial for you to maintain a clean copy of the code (as in, self-contained and not part of your bigger project) with your changes in a separate repository which you explicitely forked from the original repository ("upstream") on Github (but you can also do it privately with git itself). This gives you the advantage of git's features regarding keeping track of changes and merging them between upstream and your fork. The source used by your bigger project is your own forked repository, which you may or may not keep in sync with upstream. This fork is also a starting point for any pull requests you may have in mind for upstream.
When you fork a repository on GitHub, the original author is able to see your fork and therefore that their work is being used. Also if you find and file bugs or suggest improvements you are giving positive feedback to the author. Finally, a pull request is the crown jewel of showing your appreciation. But as a developer who publishes stuff on GitHub, it is never my expectation to receive any of it.
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
We don’t allow questions seeking recommendations for books, tools, software libraries, and more. You can edit the question so it can be answered with facts and citations.
Closed 7 years ago.
Improve this question
Normally, to analyse big C projects, I prefer grep/GNU command line tools, lint, simple Python scripts. Saying "to analyse" C project I mean to collect code statistics, to understand project's structure, its data structures and flow of execution - what function calls what, entry points in different modules, static members, threads, etc. But it works not so good with an object-oriented code.
Whenever I have a big C++ (or Objective-C) project, containing large number of source files and several directories, I would like to see it's class diagram, data fields, methods, messages, instances, etc.
I am looking for a most Unix way solution. Can you help me?
Doxygen is the closest i could find, when i was searching last time. It is not unix way, but it is available free for linux/windows/mac. It generated descent graphs for me. Hope it helps.
http://www.doxygen.nl/
http://en.wikipedia.org/wiki/Doxygen
With message passing and dynamic dispatch going around you are pretty much screwed. It doesn't even depend on language, message is as well used in C++ world. There is no tool that can analyze the code and tell what the application flow will look like. In those cases, the whole data/execution flow may depend on configuration files, how you hook up producers/consumers together etc.. and change significantly. If you are lucky, there would be some high-level documentation, maybe with pictures and description of overall ideas etc. Otherwise, the only option here is to run it under debugger for any given configuration and see what is going on in there, step by step. Isn't that a true UNIX way?
Your request is for a variety of views, some text-based, some structure based.
You might consider Understand for C++ which does a mixture of these. Don't know if it does ObjectiveC.
Our Source Code Search Engine (SCSE) is rather more limited, but provides a much faster way to "grep" than grep does. For large code bases this matters. It will handle multiple languages and dialects. We don't have an Objective C dialect, but I think our C or C++ front ends would actually work pretty well for this, since Objective C uses pretty much the same lexical syntax.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I just stumbled upon Adobe source libraries, ASL. It is set of templates and functions similar to boost, under MIT license.
Some of the utilities in the library I found quite useful and now I consider using it.
the library seems pretty straightforward, however.
Have you used ASL yourself? if so, what were your impressions? do you recommend it?
does it work well with a range of compilers and platforms e.g. IBM C++, ICC, g++?
have you encountered quirks/unexpected things?
thanks
ASL uses Boost heavily, so it's not such similar to Boost, as (in some cases) a relatively thin wrapper around Boost.
The "big" pieces of ASL are Adam and Eve. Most of the rest appears to be (and if memory serves, really is) little more than support for those.
ASL hasn't been updated in a while, and if I'm not mistaken some of what it provides in wrappers around Boost has now been incorporated into the Boost libraries themselves (most Boost authors have been aware of ASL at least since they featured in Sean Parent's keynote presentation at Boostcon 1).
My own experience with them has been somewhat mixed. At one time, I used a couple of their Boost-wrapper classes a bit, but IIRC, within the next release or two, the bits I cared about were available in Boost without any wrappers (though offhand, I don't remember exactly what those pieces were...)
Adam and Eve are kind of cool for playing around with different UI layouts and such -- but I've never used them for a finished version of a program. At least to me, it appears that they're useful primarily with a relatively complex UI. My impression was that if you find them very useful, your UI probably needs work. If you need Adam and Eve to help understand what's going on, chances are your users can't figure out either.
OTOH, there are probably at least a few cases where a dialog is clear to a user, but the code much less so to a developer. If you do a lot of disabling some controls until values have been entered in other controls, and such, it can make it a lot easier to ensure controls are disabled until all values they depend upon have been entered.
As already noted, thew whole point of ASL is Adam and Eve, the rest are just handy tools.
Adam & Eve work together to describe UI with auto-layout in a cross-platform way.
If this is not what you need, then you should probably not spend much time on ASL.
Eve has the typical collection of vertical/horizontal/other containers for auto-layout.
And scripting with Adam allows you to achieve things difficult (if not impossible) to achieve just with layout containers (things like keeping separate groups of controls the same size, for instance).
True, you implement some of the rules in your C++ code. But it makes sense to store the UI description rules related to UI behavior in the same place where you store the UI to begin with.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I am writing a C++ static library and I have been commenting with doxygen comments in the implementation files. I have never really had to care very much about documentation but I am working on something now that needs to be documented well for the users and also I am trying to replace my previous bad habit of just wanting to code and not document with better software engineering practices.
Anyway, I realized the other day that I need a couple different types of documentation, one type for users of the library(doxygen manual) and then comments for myself or a future maintainer that deal more with implementation details.
One of my solutions is to put the doxygen comments for file, class, and methods at the bottom of the implementation file. There they would be out of the way and I could include normal comments in/around the method definitions to benefit a programmer. I know it's more work but it seems like the best way for me to achieve the two separate types of commenting/documentation. Do you agree or have any solutions/principles that might be helpful. I looked around the site but couldn't really find any threads that dealt with this.
Also, I don't really want to litter the interface file with comments because I feel like it's better to let the interface speak for itself. I would rather the manual be the place a user can look if they need a deeper understanding of the library interface. Am I on the right track here?
Any thoughts or comments are much appreciated.
edit:
Thanks everyone for your comments. I have learned alot from hearing them. I think I have a better uderstanding of how to go about separating my user manual from the code comments that will be useful to a maintainer. I like the idea that #jalf has about having a "prose" style manual that helps explain how to use the library. I really think this is better than just a reference manual. That being said...I also feel like the reference manual might really come in handy. I think I will combine his advice with the thoughts of others and try to create a hybrid.(A prose manual(using the doxygen tags like page, section, subsection) that links to the reference manual.) Another suggestion I liked from #jalf was the idea of the code not having a whole manual interleaved into it. I can avoid this by placing all of my doxygen comments at the bottom of the implementation file. That leaves the headers clean and the implementation clean to place comments useful for someone maintaining the implementation. We will see if this works out in reality. These are just my thoughts on what I have learned so far. I am not positive my approach is going to work well or even be practical. Only time will tell.
I generally believe that comments for users should not be inline in the code, as doxygen comments or anything like that. It should be a separate document, in prose form. As a user of the library, I don't need to, or want to, know what each parameter for a function means. Hopefully, that's obvious. I need to know what the function does. And I need to know why it does it and when to call it. And I need to know what pre- and postconditions apply. What assumptions does the function make when I call it, and what guarantees does it provide when it returns?
Library users don't need comments, they need documentation. Describe how the library is structured and how it works and how to use it, and do so outside the code, in an actual text document.
Of course, the code may still contain comments directed at maintainers, explaining why the implementation looks the way it does, or how it works if it's not obvious. But the documentation that the library user needs should not be in the code.
I think the best approach is to use Doxygen for header files to describe (to the users) how to use each class/method and to use comments within the .cpp files to describe the implementation details.
Well done, Doxygen commenting can be very useful both when reading code and when reading generated HTML. All the difficulty lies in Well done.
My approach is as following:
For users of library, I put Doxygen comments in header files for explaining what is the purpose of that function and how to use it by detailing all arguments, return values and possible side effects. I try to format it such that generated documentation is a reference manual.
For maintainers, I put basic (not Doxygen) comments in implementation files whenever self-commenting code is not enough.
Moreover, I write a special introductory file (apart from the code) in Doxygen format for explaining to new users of libray how to use the various features of the library, in the form of a user's guide which points to details of reference manual. This intro appears as the front page of the Doxygen generated documentation.
Doxygen allows the creation of two versions of the documentation (one for users and one for "internal use") through the \internal command and the INTERNAL_DOCS option. It is also possible to have a finer grained control with conditional sections (see the \if command and the ENABLED_SECTIONS option.)
As others have already noted, it is also useful to provide users (and also maintainers sometimes) something at a higher level than strictly code comments. Doxygen can also be used for that, with the \mainpage, \page, [sub[sub]]section and \par commands
I recommend you to take a look at this paper: http://www.literateprogramming.com/knuthweb.pdf
I normally applied those ideas to my projects (using Doxygen). It also helps in keeping the doc up to date because it is not necessary to leave the IDE, so one can make annotations while coding and, later on, revise the final pdf document to see what needs to be updated or more detailed.
In my experience, Doxygen requires some work so that the pdf look nice, the graphs and pics in place, etc. but once you find your ways and learn the limitations of the tool, it gets the job done quite well.
My suggestion, besides what Kyle Lutz and Eric Malefant have already said, is to put long explanations about related classes in its own file (I use a header file for that) and add references to other parts using Doxygen tags. You only need to include those headers in the Doxygen configuration file (using pattern matching). This avoids cluttering your headers too much.
There is no quick easy answer, good documentation is hard.
I personally feel a layered model is best.
high level docs in prose. Pictures and videos are very appropriate.
reference level docs should Doxygen (well done doxygen, not just off hand comments).
maintainer docs should not show up in the reference docs, but they could still be doxygen as pointed out by by Éric.
I really like the documentation style used in RakNet. The author uses extensive Doxygen comments and provides a generated reference manual. He also provides some plain html tutorials. Best of all he supplies video walk-throughs of some of the more complicated features.
Another good example is SFML. The quality isn't as good as RakNet but it's still very good. He provides a good overview page in the doxygen generated documentation. There are a few plain html tutorials and a plain html Features/Overview page.
I prefer these styles as Doxygen generated documentation is generally too low level when I'm just starting out, but perfectly concise once I'm in the groove.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
What do you think is best practice when creating public header files in C++?
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.
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.
I would definetely have some documentation in the header files themselves. It greatly improves debugging to have the information next to the code, and not in separate documents. As a rule of thumb, I would document the API (return values, argument, state changes, etc) next to the code, and high-level architectural overviews in separate documents (to give a broader view of how everything is put together; it's hard to place this together with the code, since it usually references several classes at once).
Doxygen is fine from my experience.
I believe Doxygen is the most common platform for generating documentation, and as far as I know, it's more or less able to cover JavaDoc-notation (not limited to of course). I've used doxygen for C, with OK results, I do think it's more suitable for C++ though. You might want to look into robodoc as well, although I think Occam's Razor will tell you to rather go for Doxygen.
Regarding how much documentation, I've never been a documentation-fan myself, but whether I like it or not, having more documentation always beats having no documentation. I'd put the API-documentation in the header file, and the implementation documentation in the implementation (stands to reason, doesn't it?). :) That way, IDEs have the chance to pick it up and show it during autocompletion (Eclipse does this for JavaDocs, for example, perhaps also for doxygen?), which shouldn't be underestimated. JavaDoc has this additional quirk that it uses the first sentence (i.e. up to the first full stop) as a brief description, don't know if Doxygen does this though, but if so, it should be taken into consideration when writing the documentation.
Having a lot of documentation runs the risk of being out of date, however, keeping the documentation close to the code will give people a chance to keep it up to date, so you should definately keep it in the source/header files. What shouldn't be forgotten though is the production of documentation. Yes, some people will use the documentation directly (through the IDE or whatever, or just reading the header file), but some people prefer other ways, so you should probably consider putting your (regularly updated) API documentation online, all nice and browsable, as well as perhaps producing man-files if you're targeting *nix-based developers.
That's my two cents.
Put enough into the code that it can stand alone. Nearly every project I've been in where the documentation was separate, it got out of date or wasn't done, partly that if it's a separate document it becomes a separate task, partly as management didn't allow for it as a task in budgetting. Documenting inline as part of the flow works much better in my experience.
Write the documentation in a form which most editors recognise is a block; for C++ this seems to be /* rather than //. That way you can fold it and just see the declarations.
Maybe you would be interested in gtk-doc. It can be "a bit awkward to setup and use" but you can get a nice API documentation from source code, looking like this:
String Utility Functions