I'm using Natural Docs to document a language that is not directly supported by it - Matlab to be precise. At times I want to include parts of the Matlab source code in the documentation as the code itself is commented fairly well.
I don't want to reproduce the entire code and comments in a comment block using the --- Code comment, so is there a way to indicate that I would like a particular code section to be documented "as is"?
Related
Official and most of yaml documentation is written in yaml itself. That is nice demonstration of language power. I get it, that's the main point of this documentation. But documenting language by using that yet unknown language is like solving puzzle. At least for me. Searching in this style of documentation really hard: "which operators can I use for string indentation?" In traditional documentating style one would use chapter say "string indentation". But here, while it's a nice demo, you need to read it all, and understand it all, which is extra subpar if you don't work with yaml daily. And yaml language spec is great, if you want to practice context (free?) grammar definition, but greatly unfit for quick search for basic questions.
My question is. Is there yaml documentation, using traditional structure, documenting most of features, not just very few? One html page, sections and paragraphs? I cannot find one, and I'm always struggling/wasting so much time trying to find something in this style of documentation. And every time I read anything, I feel I'm missing so much information, which is not shown, constantly learning X using not yet explained constructs.
Is it possible to write documentation in source files like in Common Lisp or Go, for example, and extract it from source files? Or everybody uses Scribble to document their code?
The short answer is you can write in-source documentation by using scribble/srcdoc.
Unlike the other languages you mentioned, these aren't "doc strings":
Although you can write plain text, you have full Racket at-expressions and may use scribble/manual forms and functions.
Not only does this allow for "richer" documentation, the documentation goes into its own documentation submodule -- similar to how you can put tests into test submodules. This means the documentation or tests add no runtime overhead.
You do need one .scrbl file, in which you use scribble/extract to include the documentation submodule(s). However you probably want such a file, anyway, for non-function-specific documentation (topics such as introduction, installation, or "user's guide" prose as opposed to "reference" style documentation).
Of course you can define your own syntax to wrap scribble/srcdoc. For example, in one project I defined a little define/doc macro, which expands into proc-doc/names as well as a (module+ test ___) form. That way, doc examples can also be used as unit tests.
How Racket handles in-source documentation intersects a few interesting aspects of Racket:
Submodules let you define things like "test-time" and "doc-time" as well as run-time.
At-expressions are a different syntax for s-expressions, especially good when writing text.
Scribble is an example of using a custom language -- documentation-as-a-program -- demonstrating Racket's ability to be not just a programming language, but a programming-language programming language.
my only coworker used the following code execution to compile code to pdf
compile to pdf (1st time): produce a first draft version and an .xlsx. but the only purpose is to create the .xlsx.
compile the same file to pdf (2d time): look up in the previously created .xlsx to produce the pdf
To have the process in one pass, simplified and avoid a source of foreseeable bugs (2 pass compilation... hell), I mentioned that we could:
reorganize the code
use 'in-line' code functionality (code in the latex area)
his answer was something like
well it works if you follow the step I describe so no need to change
it and it is written in the comments that you have to compile it twice.
I had to take the time to write the step on a paper. We let non-programmer run this code to produce reports. They don't read comments.
if I refactor the code he will really be upset, because it is not the way he started with plus as mentionned it works if you follow his instruction.
did you already faced it. how did you resolved it?
thanks
I want to store brief snippets of code in the database (following a standard signature) and "inject" them at runtime. One way would be using eval(my_code). Is there some way to debug the injected code using breakpoints, etc? (I'm using Rubymine)
I'm aware I can just log to console, etc, but I'd prefer IDE-style debugging if possible.
Hm. Let's analyze your question. Firstly, it does not seem to have anything to do with databases: You simply store a code block in the source form somewhere. It can be a file, or a database. Secondly, you don't want IDE-style "debugging", but TDD-style. (But don't concentrate on that question now.)
What you need, is assertions about your code. That is, you need to describe what output should your code produce given some input examples. And then, you need to run that code and see whether its function matches the expectations. Furthermore, if you are not sure about the source of your snippets, run them in a sandbox (with $SAFE = 4). If your code fails the expectations, raise nice errors (TypeError, or even better, your custom made exception), and then you can eg. rescue those exceptions and eg. use some default code snippets...
... but maybe I'm not actually answering the same question that you are asking. If that's the case, then let me share one link to this sourcify gem, which let's you know the source, so that you can insert a breakpoint by saying eg. require 'rdebug' in the middle of code, or can even convert code to sexps. That's all I know.
I'm using the DyninstAPI (namely, the SymtabAPI component) to rewrite the symbol tables in binaries. I'm using the following methods to do so:
data_region->setPtrToRawData((void*) new_raw, data_region->getRegionSize())
The method returns successfully, I check my error codes, and I even re-read the data section which has successfully been replaced. The problem is that the original binary isn't rewritten with the new raw .data section, and the original raw .data section persists.
I've scoured the manual to see if there is some sort of commit function but none is documented and nothing of the sort is mentioned in the examples. EDIT: I just read through some of the source code for the Region class, and it looks like I'm essentially doing what patchData does (in case that is the method I should be using).
Suggestions?
The programming manuals are available at http://www.paradyn.org/html/manuals.html.
P.S. hopefully a more reputable user can add the tags DyninstAPI and SymtabAPI for me.
After consulting with the developers, they alerted me that the function I needed to call was emit and the syntax I ended up using was:
symtab_obj->emit("new_binary.out");
Thanks Drew!