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 using PHPDoc and JSDoc for my source code. I know that there are tools to build an API out of those docs. However, what I am wondering is that how is one supposed to explain complex code? Do I just use multiline comments inside functions rather than explaining in the PHPDoc/JSDoc?
For example, consider this code:
/**
* Lorem ipsum dolor sit amet.
* #param {Integer} width
* #return {Boolean}
*/
function setWidth(width) {
// Very complex code goes here...
}
In the above case, how should I go for commenting the complex code? I do not think I can do that in the JSDoc since it is used for building an API (which is about "how to use" rather than "how things work"), right?
Are my assumptions correct:
JSDoc/PHPDoc is solely written for those who are going to use the function/method.
Comments within the function are written for anyone who needs to understand the logic behind the function/method.
Documentation is separate from API and source code comments, the documentation (that every software should provide) is written for those who want to use the software.
But what I do not understand is that what explains the software in an architectural level -- should there be a developer documentation, too?
What are your strategies to perfect documentation?
You document Public Interfaces with those tools, you don't want consumers of the API to know or care about the implementation details, you put those comments in the code itself. Also "perfect" documentation is not really a good goal. The BEST documentation is working example code that uses the Interfaces in a obvious manner. Unit tests fit this requirement nicely in most cases.
If you really feel the need to document something about the inner workings of a function, that mainly only the developers of the code need to know, phpDocumentor does have the #internal tag.
When you use the --parseprivate runtime option, non-public code elements (like private variables, protected methods, etc) become visible in your generated documenation. Text that you include via the #internal tag also becomes visible.
It sounds to me like the descriptions that you want to write regarding the internal method code would be good candidates for such #internal usage.
Related
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 8 years ago.
Improve this question
Lua beginner here, i am looking into lua.
my question is: since an object in Lua is just a table,
new fields can be added at runtime. if I have a typo in the code, and instead of changing a field, I create a new field, won't that bring mayhem? ;)
I would only be able to figure out the bug in runtime, if I even get to that point in the program.
(of course the table concept has other benefits like meta programming without reflection, but my question is about "safety" or predictability.)
Is that the right conclusion?
Yes, that is correct.
When working with a dynamically typed language, you'll need an extensive suite of unit tests, to make sure you cover all possible scenarios and prevent the kind of mayhem you described.
If you want to protect yourself from this, I'd recommend looking at a static typed language, such as java, c# or scala, and let the compiler do the type-checking for you.
This is why Twitter moved from Ruby to Scala - as the project grows, it gets progressively harder to keep track of bugs that can only be verified at runtime using a dynamically typed language - but could be verified at compile-time by a static language compiler.
Dynamic typed languages are based on duck typing:
If it walks like a duck, and quacks like a duck, it is a duck
I prefer this version:
If it walks like a duck, and quacks like a duck, it’s probably gonna throw exceptions at runtime.
Lua gives you the mechanisms to have at least as much safety as other dynamic programming languages with baked-in object models do. See here for instance.
Errors will still happen at runtime only though, so you need a test suite with decent coverage.
There are projects to add static typing to Lua. Fabien Fleutot, who created metalua, presented his at the latest Lua Workshop. See:
his slides
a high-level overview of his work
a more formal paper about it
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 9 years ago.
Improve this question
I would like to know if there is any language that compiles to VBA, like we have coffeescript for js, less for css...
If there is not, is there something that prevents us from achieving that? Would it be a bad idea?
I guess that would help people that are used to work with more modern languages to be a LOT more productive.
What would it take to do that ? Could we reuse the coffeescript grammar and parser, but hack into the steps that generate Javascript and generate VBA instead ? A subset of VBA would be just fine.
In general, it's always possible to compile from one Turing-complete language to any other. The result might not be fast, but it's generally fairly straightforward.
So, why was Coffeescript created ex nihilo, instead of using an existing language? Integration.
Suppose, for example, that we wanted to write JS in Haskell. You could easily implement a Haskell to JavaScript compiler. Now, suppose, writing in Haskell, you wanted to pop up a dialog box on a Web page. In JS, you'd write alert("hello"), but if your H2JS compiler is correct, there won't be any alert function, because Haskell functions don't have side-effects (perhaps the whole reason that you wanted to write in Haskell was so that you could have nice guarantees like that calling functions won't pop up dialog boxes).
There are many ways that your H2JS compiler could provide this functionality, but it's not necessarily obvious which one was chosen. You can't just read JavaScript documentation to learn how to do browser-y things; you also need to read the documentation for your H2JS compiler!
On the other hand, Coffeescript is similar enough to JS that it's pretty obvious how to pop up alerts, edit the DOM, etc., just from knowing how it's done in JS.
So, it's not hard to do in a slapdash way, but, if the source language is much different from VBA, it'll likely be tricky to do the VBA-specific things that make the project useful in the first place.
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 looking into writing documentation about some functions but do not want to write the documentation in the source code.
Is there a template I can follow, e.g XML, or something which can generate some sort of Javadoc-ish looking style documentation?
There's docbook, but to be fair, docbook excels at book or manual style documentation. It does do website documentation, but its websites tend to not be as heavily interlinked as javadoc. This is an example of a docbook document rendered to a website.
Docbook excels when you have one "source document" that doesn't have a presentation in the real world, and a few "rendered documents" that all must contain correct, up to date information built from the source document.
It is hard to understand what you are looking for, mainly because it seems that you are not exactly sure yourself. Javadoc is documentation that was purpose designed to document Java code, so a "javadoc like documentation without source code" is a hard idea to follow. Perhaps if you sat down and thought about the main sections of documentation, you'd find an outline (which might heavily include the navigation you want to use). Then it would be much easier to fill in the blanks, because you have blanks.
You can use the javadoc engine to generate documentation. It is very configurable; and supports two kinds of plugins. One to add additional "tags" and one to add / override additional "layouts". However, these tags and layouts operate on an API that tends to be Java source code oriented, such that a "javadoc comment before a class" calls a method that effectively handles the javadoc for this class. As such, without Java source code (or something very like it) you have the wrong underlying API (unless you can bend it to your needs).
Maybe you are looking for something like Doxygen, an API-documentation tool that can also be used to write other documents (f.ex. the manual of doxygen was produced with Doxygen itself without normal source code.)
Another tool would be Sphinx, which can also be used for API-documentation and also manuals without source code (ex: Python documentation).
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
Im trying to find a piece of software to help a small (~3-5 people) team write A) a user guide and B) an API reference for the extensible parts of the software. We quite like the idea of using a wiki of some form, but have a few specific requirements:
The ability to export the manual(s) into both online and offline readable forms (eg, a bunch of HTML files that can be put on a web server or read locally)
Automatically create pages from XML documentation. We are writing in VB.Net/C#.Net, and most of the API specific stuff already has XML documentation comments. It would be great if the API portion of the manual could specify the classes, methods, arguments etc, but also allow the writers to link to these pages from others. (eg, have a page that details the foo class, and be able to have a page that details how to do some general task with the API link to the page for the foo.increaseBarCount() method).
That's just about it, other than the obvious ('easy to use', 'do all the writing for me so that i can get out of the tedium of writing technical documentation', 'not cause a global thermonuclear war').
Does such a piece of software exist? Can a similar system be cobbled together using mediawiki extensions?
As to "automatically create pages from XML documentation", the obvious solution would by doxygen. It creates documentation (HTML, PDF, WinHelp ...) from special doc comments embedded in source code. It handles Javadoc comments, Qt style comments and XML comments. If you generate HTML, the page names are predictable, so easy to link to; doxygen can also create internal links automatically. If you use other formats, you can probably embed some sort of anchor to refer to page names, but I'm not quite sure about that.
With respect to general documentation, we have good experiences with using a wiki. We use MediaWiki (of Wikipedia fame), but any decent wiki will probably do.
We have never tried printing it, but Google shows various solutions for printing from MediaWiki, so you can probably make something work without too much hassle.
The main thing we like about using a wiki for docs is that you can easily change them when you detect a mistake; that keeps them fresh. Also, no worries about having an outdated copy.
You could check out Atlassian Confluence. I believe that they have a free version (possibly just an offer, so you may end up paying in the long run, don't know) for small teams. They also have an API, so it wouldn't be too hard to write a utility to extract the XML C# documentation and create pages from it using the API, if nothing already exists.
The wiki is easy to use and is used quite a bit by open source projects. You can look at
the ANTLR Documentation, which is Confluence, for an example.
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
Is it my browser that doesn't work with their API online documentation?
The structure of it seems to be very bad compared to the Java API online documentation and the Yii API online documentation.
I am new to Zend Framework, so I wonder, should it be like that?
I think the API is nice, the only problem sometimes they don't give real meaning of arguments
After the API is maybe a bit behind some java examples, but I find the reference guilde quiet impressive and complete. You've got 900 pages describing every piece of the framework with short code snippet that's just wonderful.
Personally I use more often the reference guide then the API documentation.
I've been digging into Zend Framework for about a month now. I'm starting to catch on but I have to agree with the initial comment. The API documentation, at least what is available, is atrocious. What is this Dojo stuff anyway? I would expect a proper, standardized API reference for something as extensive and powerful as the Zend Framework. For an experienced software engineer the reference manual is really introductory material. Once it is digested all that is really needed is a good API reference that clearly shows properties, methods, inheritance tree, with brief descriptions where necessary. Like Java, AS3, etc. I could have saved myself about two weeks of time had I had full access to the API. I don't get it, but I intend to persevere with ZF.
For me the problem is the reference guide simply lists through all the components and has a massive page telling very long-haul uses of each component with no sort of scope of where said code should appear in your work flow.
I believe it should be re-factored to be like CakePHPs documentation, where each page is targeted at getting a specific task done, like "Saving Your Data", "Deleting Data", "Validating Data" and so on.
Real life examples with context are a lot more useful then the Zend Docs where I tend to have to guess where certain variables (commonly $db) come from - and in full MVC cases, does't even apply.