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 have several projects, some using managed code and some using only unmanaged. All have the XML comments have been added and the XML documentation is being generated correctly (the generated xml file and intermediate the xdc files).
Surely there's something that can take these files (the output of xdcmake) and generate MSDN style chm help! ?
From what I understand, both doxygen and sandcastle ignore that obvious step and re-invent the wheel to re-scan your code. (there's also the fact that sandcastle is apparently useless for non-.NET projects).
Having tried doxygen (horrible output, but fast) and sandcastle (nice MSDN style output, but sloooooow) both are begging to be outdone by something much simpler.
It would also be nice if there was some kind of editor associated that we can also write the 'Getting Started' and 'Information' kind of pages that are also needed with any API documentation.
Does anyone know of any solutions?
You might want to try DoxyComment. Here is the description from Doxygen's Helper tools & scripts:
An addin for Visual Studio 2005 called
DoxyComment was created by Troels
Gram. It is designed to assist you in
inserting context sensitive comment
blocks into C/C++ source files.
DoxyComment also comes with an xslt
template that lets you generate
documentation like the MSDN library.
Honestly, Sandcastle is your best bet. I know it can be a bit of a pain to configure, but the documentation is exactly the style you are looking for.
I know the project where people still use NDocConsole
However I suppose that NDoc is a dead project, because on http://ndoc.sourceforge.net/ there are no updates since 2005
Related
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 6 years ago.
Improve this question
I know that it is possible to use markdown inside comments and doxygen can understand it. But I need to know if it is possible to generate the documentation in markdown format?
I need these documentation to be generated from C++ files.
I know this question is old but there seems to be a new tool available: https://www.npmjs.com/package/doxygen2md
I don't know of anything that will do it directly, but doxygen has the ability to output an XML document using the XML generator.
There are various projects out there that can then consume said XML data to transform it, one of the simplest ones that I am aware of is Breathe which is used to convert the XML documents to something that Sphinx can use to output documentation using doxygen as a pre-processor so to say.
The code for Breathe may be simple enough to use as a starting point to then generate Markdown files instead of the ReStructuredText files that Sphinx requires. I haven't looked at the code for Breathe, but I have used it for some major projects.
Generate XML with doxygen http://www.doxygen.nl/manual/customize.html#xmlgenerator.
Use PanDoc http://pandoc.org/
to convert XML to Markdown.
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 am looking for a plugin(s) for VS2010 that will allow me to:
Document my code easily.
Browse that documentation.
Export it into some format or other.
I was looking for a sort of front-end for doxygen + a documentation browser, but found nothing. Any other such tool will be great, it doesn't have to be doxygen, although it should preferably be free.
Thanks
My addin, Atomineer Pro Documentation, will help you a lot with generating and updating documentation comments. It will save a huge amount of time creating the comments as it not only provides boilerplate commetns, but also fills in as much documenation as it can to help minimise the typing you need to do to complete the docs. It makes it extremely easy to keep the docs in sync with the code. It supports comments in Documentation Xml and Doxygen (Qt or JavaDoc) formats, and the style and layout of comments is highly configurable. It handles C++, C, C++/CLI, C#, Java, and Visual Basic.
You can then process the documentation comments using Doxygen (which also handles DocXml, Qt, JavaDoc formats) to produce external (e.g. html) documentation.
JavaDoc/Qt format comments can be made more readable than XmlDoc, but it's worth considering that Visual Studio supports XmlDoc (so you get syntax colouring in the comments, code analysis tools like FxCop and StyleCop can check the content for you, and in some languages the intellisense system can show your documentaton in tooltips as you write client code, etc. So XmlDoc is steadily gaining a lead over the other documentation formats due to the VS IDE support for it).
Why don't you just use the official Doxygen GUI? The documentation is usually generated within seconds and it can generate very nice HTML files.
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 6 years ago.
Improve this question
I am looking for some basic information regarding makefile structure. Any pointers will be highly appreciated. Thanks.
Official NMAKE documentation.
There are several other types of build systems that use "makefiles". Several of the other answers here are pointing you to these other systems. They all implement the same basic ideas, but the capabilities and syntax vary, sometimes in subtle ways. If you need to learn how to use NMAKE (which is the one you mentioned in the title), and you read GNU make documentation, you're likely to get confused.
The best help I think I can give anyone desiring to learn how to write their own makefiles is:
DON'T DO IT!!!
Use a makefile generator. There's a lot out there. One of the best I've seen is CMake but there's also automake/autoconf/all that.
You can also use a totally different build system like Ant (but that's by far the only option in this category).
Make actually kind of sucks. I haven't touched one in 10 years. Put your development effort where it will do the most good, in your code.
For very quick start (if you haven't yet tried) - read this, very simple.
If you want start writing makefiles in couple hours - this one.
To be a monster in makefiles use official, commonly you need this as reference book.
You may want to have a look at the Autobook
I agree with most earlier responders: don't continue to be dependent on NMake, use newer tools. Ant, MSBuild, Maven, Scons, GNU/autotools, etc. But, if you really want to learn more about NMake, check out the Microsoft Rotor (SSCLI) source distro, it includes the source to NMake, at least a hacked-up snapshot needed to bootstrap Rotor's build. And for better examples of Nmakefiles, look in early Win32 SDKs, and later OS/2 SDKs, that was the heydey of complex Nmakefiles.
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 am using Visual Studio and an external library that is commented in doxygen-style. Is there any way to display doxygen documentation in the editor tooltip like DocXML?
The VS plugin Visual Assist shows doxygen comments. From what I can see, it doesn't actually process them, but it shows doxygen comments (in their raw form) nevertheless.
There's a trial at their website.
Be warned, though. I have seen very few C++ programmers who tried it for a few days and were not begging their managers to buy it for them afterwards.
Not that I am aware of (though I'd love to hear if there is a solution, as doxygen format is much more readable than XML).
A "workaround" I can suggest is that my AtomineerUtils add-in can bulk-convert Doxygen format comments into DocXML, which is then picked up and used for Intellisense tooltips. (And Doxygen is able to read DocXml, so you keep most of that functionality too). Currently the conversion is a fairly simple one, but I'm working on some improvements at the moment that should make it much more flexible with respect to input comment formats.
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
The thing that really turns me off about Boost is their documentation. What I need is a good reference, and instead of explaining what a good reference is to me I would give example:
java.sun.com/javase/6/docs/api/
Yes I love it. It is also this:
cppreference.com/wiki/stl/vector/start
On the other hand what I find about boost is something like this:
http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm
Basically some long page of text. Almost no formatting, some bold text here and there and hopefully some links between elements. Not to mention that smart_ptr is one of the better documented libraries.
If you do not find the difference between this and the above examples please stop reading and ignore this post. Do not get me wrong, I write C++ and I use Boost. At my firm we use at least 4 of their libraries, still each and every time I need to check a method prototype for instance it gets me out of my nerves scrolling through their essays. And yes I know that Boost is a collaborative project and that different libraries are developed by different teams.
So does any of you share my disappointment with Boost's reference and do you know some better site documenting the Boost libraries?
In general, I don't find the documentation is that bad. In general again, the information is "somewhere" in there. The main problem I see is a lack of uniformity, making it difficult to find that "somewhere". As you write in your question, the docs were written by different people, and a different times, and that's probably the cause for this lack of a common structure.
From the java and cppreference links you cite in example, I infer that you are more interested in the synopsis of the interface than in "tutorial" or "motivation" stuff. For shared_ptr, does http://www.boost.org/doc/libs/1_40_0/libs/smart_ptr/shared_ptr.htm#Synopsis provide what you're after?
For some libs, the "test" and "example" directories under libs/<library_name> are useful.
You may post your questions, comments and suggestions on the boost users and/or documentation mailing lists. From what I see there, specific documentation improvement suggestions are normally welcomed by the library maintainers.
If you are looking for an introductory text I found the Bjorn Karlsson book very good. It was a while ago when I read it so there may be more up to date texts available now. Find it here.
I most definitely agree. Javadoc is nasty, nasty stuff. But it is thorough and consistent across nearly every project. Compare the browsability of a random Jakarta project's documentation with that of a random Boost project.
Looking at the Java link provided, well more than half of it is obsolete for quite some time now :)
You have PDF tools and PDF format of the docs now.. There are tools and more on its way, from boostbook for lib writers ages ago to synopsis and more.. Build your own or parse existing majority of markup cost to an already overblown project :)