Comments (15)
Personally, I don't like Doxy tagging; it's the sort of thing that doubles the edit work when changing
something and repeating the parameters of a function in comments is just torture for me.
The result is that the tags are always less well maintained than the code, so out of date or missing
and I prefer to not doxy tag and simply aim for maximum clarity and readability in the code.
I think that an API definition document is smart, something in latex that is written in the style of the
present QDP++ manual makes sense. Defining how the code is supposed to behave in a way that
is not simply saying "it is the current implementation" is wise. One of the things on the "TODO" list as far as I recall. Certainly something I have promised to do for RBC.
from grid.
I'm strongly in favour of this. The QDP++ manual is an invaluable introduction to the overall structure and design of the package, which is something that is impossible to gain by simply reading the code, and hence essential to newcomers.
from grid.
A good manual is really important for the final user that want to start learning the code. No doubt, and we should definitely write.
About doxygen: I found it really useful to navigate a big code, because the definition and use of classes, variables, methods, can be scattered around. Doxygen provides the tree view, the automatic links and several other things useful to quickly jump among files/definitions. Chroma without doxygen is a nightmare to learn.
from grid.
I rebump this since documentation is becoming necessary.
I remain of the view that an automatic, surfable, documentation of the code is necessary together with a thorough description a la QDP++ (which has the same issue of being up-to-date since depends on us anyway). Especially since we have so many templated classes that really needs navigation in the code to understand the full structure.
from grid.
Just wondering about this issue considering an soonish 0.6 release. Is Doxygen generation working, is there anything to do here?
from grid.
we have to make sure doxygen is optional, since not every system will have doxygen
so, adding a configure flag --enable-doxygen to build the html is the best option, with a default of "off".
from grid.
agree on it being optional with a flag.
Doxygen generation has not been tested but it should work as most of the code is just c++.
At least gives the surfable, uncommented, html.
from grid.
I can take care of that.
from grid.
Hi Guido,
I managed to create something a bit nicer with Doxygen. You can now use --enable-doxygen-doc
with configure
to enable the HTML doc. Then make doxygen-doc
build the doc. I have put that in feature/doxygen
. Could you see if it is ok for you and merge it back to develop
when everything is ok?
from grid.
Ok, let me check. Not immediately as I'm concentrating on the hirep stuff, but in time for the 0.6 release.
from grid.
Hi Guido could you please check that the new build options for Doxygen are good for you in feature/doxygen
so that I can merge it back to develop
?
from grid.
Few things that are not clear (compiling with clang, I have dot and doxygen in my path)
How to compile to get just the html? --enable-doxygen does not seem to work and the configure --help does not say much.
I tried --enable-doxygen-dot and --enable-doxygen-pdf too and in both cases it complains with an error like this in the config.log
configure:8020: error: doxygen-pdf requires doxygen-pdf
from grid.
Have you tried --enable-doxygen-doc
as in my original instructions?
from grid.
ok thanks, looks working.
Minor thing: if I modify a file the make doxygen-doc does not recognise the modification and insists that the html is up to date.
I think you can move to the develop at this stage anyway.
from grid.
Hi Guido I missed that for 0.6, I will merge it with develop
and close the issue.
from grid.
Related Issues (20)
- MPI2 romio321 library fails when reading >= 2GB per rank HOT 2
- Cannot compile the gparity and adjoint versions of the CompactWilsonCloverAction
- Compilation errors and warnings build targeting Nvidia GPUs HOT 2
- GPU Benchmark_ITT segfaults with MPI and ranks > 1 HOT 9
- Create a version of Benchmark_ITT including Clover instead of Wilson
- Grid fails to build for Nc != 3
- hipcc on Crusher: function bcopy undefined (compiler does not have openmp enabled?) HOT 1
- Certain operations involving SitePropagator::scalar_object won't compile with CUDA for Nc > 3
- make install doesn't install all headers due to duplicate Config.h and Version.h HOT 3
- Using ILDG checkpointer causes a crash during write HOT 2
- Develop is broken HOT 1
- ARM NEON is broken HOT 2
- Feature request: provenance tracking
- Add hint to shm error message
- Cuda error invalid device ordinal
- Recent commit causing Grid build to fail
- The configure options --enable-setdevice and --diable-setdevice have no effect
- Grid does not compile on Arm with CUDA HOT 9
- invalid configuration argument when running with 1 GPU
- FlightRecorder.cc breaks compilation for --enable-comms=none HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from grid.