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 two acquire functions and, besides their arguments, the documentation is identical. How should I handle this? Should I add something like "The same general notes found in function X's documentation also apply here"? If not, does Doxygen offer some kind of tool for dealing with cases like this?
ResourcePtr<T> acquire(const std::string& file);
ResourcePtr<T> acquire(const void* buffer, std::size_t size);
I don't know Doxygen, so this answer is purely on my documentation approach.
When I document in a situation like where two topics are nearly identical, I either repeat the shared information in both (preferred) or I write something similar to the following:
"Function Y is similar to function X. Function Y takes the arguments abc and [put how it works differently here]...
For more information on these functions, see ."
In this case I'd document the simpler one and add the additional info to the more complex one.
A third way is to break out the common doc from both, if that's possible.
From This Page:
Use the \sa (See Also) keyword to link to related variables, methods, or classes. This is the equivalent command to \see tag.
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 5 years ago.
Improve this question
I like good documentations for source code, but I hate the documentation comments in the code. I found solutions to separate the code from the documentation for other languages, but not for Rust. So, is any solution to separate the source code from the documentation in Rust out there?
Edit: Many years have passed and this below answer is no longer true. See the comments.
I'm afraid there's none. I am following Rust ecosystem and I have never seen even a mention of anything like that. On related note, I think the comments should be in the code, and if you writing open source code in Rust I'd advise to stick with the standard ways of doing things, just for the sake of other people. Eg. I am a vivid advocate of tab indentation as opposed to spaces ("Indent with tabs, align with spaces"), yet because Rust community settled on (clearly inferior :) ) spaces, I use spaces in my Rust projects. It doesn't fit my preferences, but after getting over it, it makes mine and other people lives easier when cooperating.
As a workaround, I would suggest making your editor just aggressively fold comments.
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 Python based source code editor. I've created a clean layout with a Gtk.Notebook. Creating a main layout was easy with Glade, but right after I imported gi.repository, everything got hard. It's very hard to find documentation. From pydoc I can 't get anything, only method signatures, which are usually *args, **kwargs. I often need to check what a method returns or takes in, and I haven't really started signals and other stuff yet.
Is there a complete/almost-complete documentation, especially for GtkSource? GtkSource is especially undocumented.
You should probably read my answer to a similar SO question: PyGObject GTK+ 3 Documentation. In short, you should refer to the GtkSourceView API Reference for C. Don't worry, it's not hard. When you see "GtkSourceView" in the C docs you know it's "GtkSource.View" in Python. When you see "gtk_source_view_new" in C docs you know it's the constructor in Python "GtkSouce.View()". You can set any GTK+ property in the constructor and there is usually get_foo/set_foo style methods for each property.
Therefore, you can do things like:
view = GtkSouce.View(indent_width=4, show_line_numbers=True)
view.get_buffer().set_text("Hello World!")
Remember, GTK+ widgets are objects so you need to pay attention to the hierarchy to find all the methods and properties for a widget.
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
Is there anything like Javadoc for documenting Fortran code? How does one document the API for the many functions they have so that they can find what they want more easily?
Not "standard", but I've used a program called "robodoc" that is able to work with Fortran.
Nowadays I believe Doxygen supports Fortran as well, which IMHO is a better tool than robodoc.
As janneb mentioned "robodoc" is clean, easy and hence useful. But you it will not analyze your program and you have to do everything yourself. On the other hand, Doxygen have incorporated the modern Fortran features(derived data types, type bound procedures, ... ) and just like C++ you can get an analysis of your program along with graphs etc.
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 spent the past few hours searching for a tutorial/documentation for QuickForm2 but seems like there is no such thing other than the examples attached with the package itself which are not sufficient at all. I tried looking through the API documentation but I can't find a method called addElement for example which is the most used method there. I just need any good tutorial about the second version of the package or would you please tell me where can i find the methods (addElement, addRule, element specific methods like setValue, setOptions, setContent ... etc).
There is a bunch of examples here (on Ubuntu):
/usr/share/doc/php5-common/PEAR/HTML_QuickForm2/examples/
If you are on another distro you can do:
locate QuickForm2
I'm not too familiar with QuickForm, but a google search found this page:
http://pear.php.net/reference/HTML_QuickForm2-latest/li_HTML_QuickForm2.html
I think you're possibly struggling because the methods you're looking for are in the base classes.
For example:
Element mentions that it Includes Node.php.
Node has an addRule method (and a setValue one).
addElement looks like its in the Container class
The documentation for HTML_QuickForm2 is in the PEAR manual: http://pear.php.net/manual/en/package.html.html-quickform2.php
addElement is in HTML/QuickForm2/Container.php.
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 thinking of making a D interface to Valgrind's client request API. By mucking around in the header files and de-compiling stuff, I could eventually figure out what it's doing but I'm wondering if their is a authoritative document on how things work? (BTW I already found this document but it doesn't have enough info)
What I'm looking for would answer questions like: How do I generate the macros to wrap/call a function that returns a 32bit machine word and takes a 64bit float?
In the valgrand manual, it describes the existing client request prototypes at the bottom of http://valgrind.org/docs/manual/manual-core-adv.html but none of these support passing 64bit floats. You could split it into two longs and pass it that way. It does look pretty hairy.
The authoritative document on how it works is the source code. If the tech docs are incomplete, then use the source.
I would also suggest looking at the sources of libraries that use the client request mechanism.