I have tried Sandcastle with the patches included with the guided GUI installation, but unless I am doing something very wrong it's basically unsuitable for documenting F# code (even if it would work really well for C#). Maybe it works for others, in which case I would be very grateful for a short complete example that I could start from. Many thanks.
I am aware of Sandcastle doesn't output everything from a F# assembly , but the project referenced there does not yet appear ready for prime time.
There must surely be something that works reliably and is "good enough"? Many thanks for any suggestions.
Edit: Many thanks to everyone who replied. Brian's answer was closest to what I wanted, so I will accept it. However, the outcome is that there does not appear to be a solution that is both suited to F# and that works reliably. I will stick with textual comments for now.
I expect FsHtmlDoc.exe will start to work at some point. While I cannot rule out that it works already and I just did not use it correctly, googling it suggests I am not the only one to find it is not yet perfect.
I know next to nothing about Sandcastle, but note that like C#, in F# you can use triple-slash comments, and they will be output in the XML documentation file that the compiler outputs (in VS, on the project properties page, build tab, check the 'Xml documentation file' checkbox; on the command line, use the --doc argument to fsc.exe.)
Also, see FsHtmlDoc.exe in the PowerPack.
You could also look at Focco
It produces a nice html based documentation. See here for an example:
You could also check out ApiStack from IntelliFactory. I realize Focco requires a very different approach if you already have a lot of standard XML doc comments.
I haven't used it, but it might be worth giving docu a try...
Related
I'm making my way into Rascal - nice work!
I'm halfway through the Tutor and might be getting ahead of myself, but one of my interests is refactoring Java. I've watched Tijs van der Storm's Curry On 2016 talk where he presents an example of this (the "TrafoFields" module around minute 16 in the video).
I was eager to get into this kind of work so I searched the documentation for the Java grammar and a similar example using it, to no avail. What's more, the library documentation has under lang::java only m3 and jdt. I reloaded Tijs' video to find he uses lang::java::\syntax::Java15. I blindly tried importing that in the Repl and it worked (albeit with lots of warnings)! I opened the Rascal .jar file to find there is even more in this package.
So my questions in this context are:
Why is this not in the documentation? I would have expected that the library documentation is exhaustive. Couldn't you at least add "TrafoFields" to the recipes?!
Is there an alternative way of finding out about such modules besides the online documentation (and apart from searching the .jar file)?
What is this weird backslash in the module name before "syntax", ::\syntax?
All good questions; and also implied suggestions for improvement. In the meantime if you get stuck please ask more questions.
Short answer: we've prioritized documenting what is used most and what is used in courses at universities and then what we've received questions about. So thanks for asking.
In reverse order:
The backslash is a generic escape to use identifiers in Rascal which are also keywords in the language. So any variable or package name or module name could be named "if" but you'd have to escape it. This helps a lot when defining abstract syntax trees for programming languages, as you can imagine where "if" would be a great name for an ast node type. "Syntax" happens to be a keyword in Rascal too.
The Rascal explorer view in eclipse can be used to browse through the library interactively. Also you can crawl the library using util::FileSystem and get a first class representation of everything that is in a library like |std:///|. Agreed, these are poorman's solutions and a good feature would a fully indexed searchable library. We're halfway there (see the analysis::text:: Lucene pre-work we've done towards supporting this.
That is a rhetorical question which I accept as a suggestion for improvement 😉😊 the answer is yes.
I've been doing web programming for some time now, and don't consider myself so much of a total newbie but I still don't understand what "/path/to" is. People use that code a lot, and I used to think it's just a way to refer to main path. But I started wondering why so many people use that syntax so uniformly, because it's confusing if it's meant to be NOT taken literally. Most people would actually type in "/path/to".
So I tried searching for "/path/to" on google, but this is something that's hard to search on a generic search engine, so no luck. So I decided to ask here. Is "/path/to" some kind of jargon that people use to refer to something? If yes, what does it exactly refer to? If no, then how does it work internally?
This is just a placeholder for an actual path in your environment. I usually use it when I want to abstract from the path in question. It does not matter and the reader/user of my code will likely have it different. So I prefer to clearly indicate what places he should amend.
Other examples of this sort:
GET http://example.com
ssh username#host
/path/to/project and similar constructs are used in documentation and blog posts to abstract away details that vary on different machines and for different people. For example, I might be working on a project on my Linux machine that is at /home/code-apprentice/src/my-cool-ruby-project. At the same time, you are working on a project on your Windows machine that you put at C:\Users\Vlad\Projects\MyEvenBetterRubyProject. We both are reading the same blog article to implement a feature. The detail of the exact path where we each store our project doesn't matter for the particular part of Ruby on Rails that we are using. The notation /path/to/project is just a convenient and concise placeholder to describe the root of the project that varies between our machines.
In an expert, I'd like to re-use the dialog that Delphi displays to edit a project's library path and for similar purposes:
I found a hack for using it (look for TOrderedListEditDlg on the page). As I think the guy who wrote the linked article knows what he does I don't have too much hope for a less hacky solution, but who knows... So: Do you know an official interface (most probably OTA) to TOrderedListEditDlg?
PS: I'm aware that it's probably trivial to recreate the whole dialog but I like consistency and the DRY principle.
You're right, I couldn't find an official way, that's the only reason I used this hack.
BTW, check out the INTAEnvironmentOptionsServices and INTAAddInOptions interfaces mentioned here. You can incorporate your configuration in Delphi's Environment Options treeview. But TOrderedListDlg still doesn't seem to be exposed officially.
I am currently working on a parser and it seems that I have made a few mistakes druing the
follow set calculation. So I was wondering if someone know a good tool to calculate follow and first sets so I could skip/reevaluate this error prone part of the parser construction.
Take a look at http://hackingoff.com/compilers/predict-first-follow-set
It's an awesome tool to compute first and follow sets in a grammar. also, you can check your answer with this visualization tools:
http://smlweb.cpsc.ucalgary.ca/start.html
I found my mistake by comparing my first/follow-sets with the one generated by this web-app
Most parser generators that I've encountered don't have obvious means to dump this information, let alone dump it in a readable way. (I built one that does, for the reason you are suggesting, but it isn't available by itself and I doubt you want the rest of the baggage).
If your parser definition doesn't work, you mostly don't need to know these things to debug it. Staring at the rules amazingly enough helps; it also helps to build the two smallest grammar instances you can think of, one being something you expect to be accepted, and the other being a slight variant that should be rejected.
In spite of having a parser generator that will dump this information, I rarely resort to using it to debug grammars, and I've built 20-30 pretty big grammars with it.
The pthread_* manpages are really, really sparse in lots of areas; for instance, for all I can tell, the various pthread_attr_set* are completely undocumented — that is, I can’t figure out what each of the various types of attributes actually do!
The only other useful sources of information I’ve found, than the manpages, are the famous pthreads tutorial and pthreads-win32 documentation… neither of which helps in this particular case, and many others.
Where else can I go for information about what pthreads’ various functions actually do, short of digging into an open-source implementation (which is quite likely over my head)?
Perhaps the actual spec for POSIX threads would help?
http://www.opengroup.org/onlinepubs/000095399/functions/xsh_chap02_09.html
I've generally found that if I want to know how something works in POSIX-land, it's easiest to go straight to the spec.
I find https://computing.llnl.gov/tutorials/pthreads/ very helpful as well.