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
Over the last year or so I've seen various announcements on the Clojure discussion list and other places about tools for documenting Clojure code. These range from full-on literate programming systems like Marginalia, and the tool being used to create the book "Clojure in Small Pieces" (or even emacs org-mode), to more conventional Javadoc-style solutions like Autodoc, and Javadoc itself which reportedly can be used with Clojure. A google search turns up various others, perhaps a few that deserve more attention, and for sure some that are just personal utilities for generating docs. My question is what are the best documentation tools, and what are their comparative strengths and weaknesses based on your experiences using them? I have not used any documentation tools to date, and am interested in experimenting with one or more.
I really like Marginalia if you want to take something like a literate programming approach. Marginalia traverses your source code, and produces an html formatted version with comments set beside code in a very clear text. Comments can be markdown formatted, making for a very readable final document. When reviewing source code that I've written some time ago, I find Marginalia really helps. Here's an example made from the Marginalia source itself.
Note that this differs from the original literate programming workflow, where you would write a file and source code is generated from that. With Marginalia, you write a regular source code file, and it's the documentation that's pulled out of that. The output is similar to what one might expect from literate programming, but this way you can still expect syntax highlighting in an editor, without any special literate programming support.
It interoperates with Leiningen, and I believe cake, though I haven't tried that myself.
Codox is a more recent documentation generator for Clojure.
Autodoc is an easy place to start and is what Clojure core and Clojure contrib produce.
Easy to use with Maven. I'm not sure if plugins exist for Leiningen or Cake.
If you want to go fully literate you should give org-babel-clojure a look. org-bable is a literate programming extension to the emacs org-mode.
If you want to use nrepl the following should be added to your .emacs:
(defun org-babel-execute:clojure (body params)
"Execute a block of Clojure code with Babel."
(let ((result-plist (nrepl-send-string-sync (org-babel-expand-body:clojure body params) nrepl-buffer-ns))
(result-type (cdr (assoc :result-type params))))
(org-babel-script-escape
(cond ((eq result-type 'value) (plist-get result-plist :value))
((eq result-type 'output) (plist-get result-plist :value))
(t (message "Unknown :results type!"))))))
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 4 years ago.
Improve this question
I regularly get frustrated by text-overload in my IDE (Eclipse right now). I find myself separating my methods by big chunks of whitespace, and then regretting that later when I need to find something by scanning through the code.
Something I think does work well is the GrepCode way of viewing source code. Does anyone know if anything like this has been implemented in a code editor? More specifically, I want the ability to have nice, formatted and colourful documentation (preferably collapsable) to help me read my code. It could even have the ability to embed design images.
"Text-overload" is precisely why a plugin like Mylyn does exist.
Mylyn's task-focused interface reduces information overload and makes multitasking easy.
Mylyn makes tasks a first class part of the IDE, integrates rich and offline editing for ALM tools, and monitors your programming activity to create a "task context" that focuses your workspace and automatically links all relevant artifacts to the task-at-hand.
This puts the information you need at your fingertips and improves productivity by reducing information overload, facilitating multitasking and easing the sharing of expertise.
Plus you can add to your project WikiText, with Markdown support (see WikiText FAQ, and its User Guide)
To better manage huge amounts of code, you may want to reconsider these:
Use Eclipse Mylyn, as it will hide code that you don't work with.
Open Windows -> Preferences, type "Folding" in the preferences dialog
and check, which editors should provide more folding by default to
hide non relevant things from you.
Have a look at the Java browsing
perspective of Eclipse. It stems from the old Smalltalk code browsing
user interfaces and is meant to more easily manage (but not edit)
Java code.
If you are working much visually with your code (and remember its layout instead of the structure), you may find the Crazy Outline view very helpful. It provides an airplane layout view of your text.
If the more important aspect of your question is how to more easily see the documentation you wrote for your code, check this:
Make sure that the JavaDoc view and the Declaraction view are opened and visible all the time to show Javadoc and declaration of whatever your cursor points at. Make sure you actually provide JavaDoc comments, to begin with.
The Eclipse Code Recommenders project has advanced documentation views, which basically show the results of data mining of common Eclipse code. You can get a company internal (commercial) version of that tool, so it would recommend code completion, as other code in your projects was written.
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 8 years ago.
Improve this question
I like F# but sometimes I need something light and cross-platform and without .NET for sure.
I tried to use OCamL many times but seems like I just can't start it.
Installed IDEA, added OCamL plugin -> Doesn't work
Installed eclipse ODT plugin -> Can't launch even config OCamL compiler - too complicated
Even had tried NetBeans plugin a long time ago but even can't deal with it.
So, for now, I'm using ocamlc -o "main.exe" "main.ml" from the command shell and different light editors. I don't use Vim or Emacs, I'm using nano and I have a habit of usage full-featured IDEs.
I found various documentation (this is looking like the best to start http://caml.inria.fr/pub/docs/oreilly-book/html/index.html for me) but still being confusing when looking for something a bit specific alike sqlite access. found this: http://neugierig.org/software/ocaml/sqlite/ with strange api annotation and no examples. And all the documentation about IDE usage I found are outdated or doesn't work.
Addition subquestion: some people told me "don't use OCamL, it's a dead language for students with low libraries support and seems like dying, use python or ruby instead". But I like the beauty of OCamL. I want to give it a try. Tell me if that is normal to use OCamL for production code today?
thank you.
There is TypeRex, a new development environment for OCaml. Here is a summary of TypeRex features:
Improved syntax coloring
Auto-completion of identifiers (experimental)
Browsing of identifiers: show type and comment, go to definition, cycle between alternate definitions, and semantic grep;
Strictly semantic-preserving, local and whole-program refactoring:
renaming identifiers and compilation units
open elimination and reference simplification
Robust w.r.t. not-recompiled, possibly unsaved buffers
Scalable (used regularly on a few hundreds of source files)
There are some screenshots available on the website. The first release candidate is out since yesterday.
EDIT: The first release (v1.0) is out now :-)
There are a few options:
Tuareg for emacs was already mentioned: http://tuareg.forge.ocamlcore.org/
vim has a few options for OCaml integration, with one good example available here: http://www.ocaml.info/software.html#vim
OcaIDE seems to be the best option for Eclipse: http://www.algo-prog.info/ocaide/
Geany, Komodo Edit and a number of other editors have syntax highlighting support for OCaml and some extra IDE-like features which are independent of the programming language being used. Most of these have limited OCaml-specific support.
OCaml is not dead. Some of the more vocal industry users of OCaml are XenSource/Citrix and Jane St. Capital. The language does not receive the same public and community evangelism that some other languages receive.
It's been years, but I really liked emacs' tuareg mode http://tuareg.forge.ocamlcore.org/
But if you're afraid of emacs, then it's not the right tool.
I specially like the shell integration and the possibility to "throw" a function you're developping in the shell and then test it.
EDIT For the subquestion, OCaml seems dead, and it's a pitty. However you cannot compare it with ruby/python. I'd say it's main competitor is Haskell which seems to be growing in popularity.
Googling "ocaml ide" shows now http://camelia.sourceforge.net/ as the first result. Haven't tested it though, so I can't really say if it is recommendable or not.
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
I am looking for something in Objective C that creates an AST out of objective c code that is modifiable. It would also be great if it also implements the visitor pattern for the AST. Basically looking for something like NRefactory is for c#.
Currently I am investigating CLang which is the only thing I have been able to google which looks close to what I want. If anyone with experience CLang can chime in, that would be great.
I am open to paid solutions as well.
Thanks!
A week since your question, and zero responses.
I'd be surprised if you found an ObjectiveC tool that let you parse and transform ObjectiveC code. Such tools are really hard to build in general, and there's
no obvious demand for one in ObjectiveC.
Clang seems like an option for processing ASTs, but it obviously isn't coded in ObjectiveC. I don't have any direct experience, but I understand Clang will parse ObjectiveC and build an AST. I suppose you can modify the AST, but I don't know if you can regenerate ObjectiveC code from that; I hear you can generate C++ code from a Clang AST for a parsed C++ program. (Clang is a tool that was really hard to build; look at its long history).
If Clang won't do, you might consider our DMS Software Reengineering Toolkit. DMS, given an explicit language description will parse, build ASTs for that language, let you inspect/modify the AST procedurally, and/or apply
source-to-source transformations written using the surface syntax of the specified language (in your case, ObjectiveC), and regenerate valid source code in the language, including comments collected during parsing.
DMS has many language descriptions, including C, Java, C++ (including C++11), COBOL, PHP, etc. There isn't presently a description for ObjectiveC, but DMS is designed to make it easy to provide such language description as might be obvious from what we already have. Compared to building the parsing/transformation/prettyprinting machinery (which was all really hard to build!), defining a language front end is a pretty small task.
EDIT June 8, 2012: (9 months after question, no other responses)
DMS now has an ObjectiveC front end. You can see a DMS-generated parse tree for a small ObjectiveC code here: https://stackoverflow.com/a/10749970/120163 Yes, DMS can regenerate valid ObjectiveC source code from such (modified) trees.
This might be helpful...
http://code.google.com/p/objectiveclipse/source/browse/core/org.eclipse.cdt.core/parser/org/eclipse/cdt/internal/core/parser/?r=981ddadee087d6bb6a27260c019df97e6e40f373#parser%2Fast%2Fcomplete
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 for a good development environment in which to work on flex or bison or both.
Are there any IDE's that have these capabilities and/or are suitable for this?
(If not the next most general question is are there lexer/parser generators with IDE's?)
Thanks
~Alex
Vim has excellent syntax highlighting support for flex / lex and bison / yacc files. Vim seems to guess from file extensions, so as long as my flex files end in .l or .lex and my bison files end in .y, it seems to work fine. I know, it's barely an IDE, but I find the syntax highlighting to be the most helpful feature for me.
ANTLR has several IDEs available, including one I wrote. By user count, ANTLRWorks is probably the most used. Mine has fewer overall features, but I use it extensively because it integrates so cleanly with my Visual Studio work. ANTLR's grammar syntax is clean and very powerful, generates code for many languages, and its generated lexers/parsers are clean, debuggable code.
Edit to address concerns in the comments:
Commercial documentation for ANTLR exists and is recommended by many, but is certainly not required. The nFringe IDE product (commercial/closed source) I worked on uses ANTLR extensively and was developed completely without the aid of the ANTLR reference book.
ANTLRWorks 1.x development is slow, but not stopped. There are currently no open issues, and two significant issues have been fixed since the latest 1.5 release.
ANTLRWorks 2 is a completely different product and was written from scratch. A separate issue tracker is available for this product.
Personally I use Gedit it has a native lex/flex yacc/bison highlighting
If you are comfortable in emacs, I would suggest these modes:
http://ftp.lip6.fr/pub/emacs/elisp-archive/incoming/bison-mode.el.gz
http://ftp.lip6.fr/pub/emacs/elisp-archive/incoming/flex-mode.el
Keep in mind that both are very buggy, but after a while I figured out most of the quirks to get the indentation working.
An example .emacs that loads these modes: http://www.elliotglaysher.org/emacs/
Just found GOLD Parsing System. It's not Flex/Bison, but if something similar is acceptable this seems to be a great IDE, and there's great getting-started documentation on the web site.
Visual studio has good support for flex/bison,
https://sourceforge.net/p/winflexbison/wiki/Visual%20Studio%20custom%20build%20rules/
To summarize, you'll need install win_flex_bison, the GNUWin port of flex and bison, and set visual studio's custom build rule using 'targets' file present along with the port, set exe path in VC++ directories settings; then it be built and debugged as usual cpp 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 5 years ago.
Improve this question
Currently the documentation where I work is in a bit of a state. There isn't anywhere near enough of it, and the documentation that does exist is spread out over many word documents making it hard to find anything.
I'm trying to take some initiative and get it improved, and I figure the first thing is to find a better format to write the documentation in:
My thoughts are that the documentation should be structured in a series of short articles (MSDN / Html Help style) and structured in a suitable tree:
It would be good to be able to produce a standalone Html-Help style package to be shipped with the application
As well as being able to produce a MSDN-style website as a reference for those who are too lazy to look at the CD.
Search is of course a must-have
It needs to be at least reasonably easy to update - if there is a 17 step process to update the published documentation then it makes it seem like too much work to do simple changes, and nobody can ever be bothered to update it.
The documentation is technical in nature, and so ideally it would be nice to be able to include generated documentation from things like the Xml documentation embedded in C# code. This is however definitely a side-requirement - currently very little useful Xml documentation exists, its just that in the future I plan to fix that.
For the same reason it is often good to be able to handle things like attachments (code samples etc...) I'm not expecting anything fancy, but this is something I need to bear in mind to make sure that its at least not handled badly.
Are there any projects or languages that are suited to this sort of documentation?
I've had good results with doxygen on my C and C++ projects although it supports many other languages as well. You put the documentation in comments in the code that can be simple or complex HTML markup. It is very easy to update as it is part of the code. You can make building the documents part of your build process. Additional topic that are not strictly API related can be added as separate HTML documents. The version I'm using doesn't support search so you would have to add another product to search these pages. Because it is HTML you can add in code samples, diagrams, etc.
If you use LaTeX you can get all your documentation in great looking PDFs and printed copies, as well as being able to generate html (via latex2html). TeX has the advantage of being all plaintext, too, so you can track/merge it reliably with your favourite revision control system.
We use confluence as our documentation repository. It is fairly easy to have public and private sections, and has a nice WYSIWYG editor. It can handle attachments and can be saved off as PDF documents if you like.
I've used robohelp with good results. it is plain html, but has a generation process that keeps everthing looking consistent. It can be packaged as a .hlp file with the app, or published to the website. Check it out, it is simple so you can get back to doing your job :)
A clean way is to use DocBook. It is easy write and undetstand. It is also easy to parse as XML parsers are standard and other forms of documentation (e.g. from the embedded documentation in comments) can be easily be transformed to this format.
It is straightforward to generate PDF, HTML og other formats from the DocBook source (tools exist for this purpose).
I've started using DokuWiki. Its not exactly what I was originally looking for (I think I was really looking for a CMS), but it does the job and some respects its better than what I originally had in mind (in particular its a wiki - I've not yet gotten as far as publishing this to our customers however so I'm not sure how well thats going to work out)
I'm using the IndexMenu plugin and the Arctic template to get a navigation tree on the left, and if I publish the wiki itself I'll use the discussion plugin to allow users to post feedback.
Currently my method of handling generated content is to use xslt templates to produce dokuwiki syntax, and write that output directrly to files / folders in the "data/pages" folder.