c++ - Should I use polyglot documentation? -

-

It is possible to touch a C ++ source file with an HTML document: 

  // & lt ;; [Ignore [/ *]] & gt; & Lt; Html & gt; & Lt; Top & gt; & Lt; Title & gt; Example & lt; / Title & gt; & Lt; / Head & gt; & Lt; Body & gt; & Lt; P & gt; Example & lt; / P & gt; & Lt; / Body & gt; & Lt; / Html & gt; & Lt ;! [IGNORE [* / #include & lt; Iostream & gt; Int main (int argc, char ** argv) {std :: cout & lt; & Lt; "Hello, world! \ N"; } / *]] & Gt; & Lt ;! [IGNORE [* / /]] & gt;

This leaves a passage // at the beginning of the HTML document, which is :

... & lt; Body & gt; & Lt; Div id = "main" & gt; & Lt; / Div & gt; & Lt; / Body & gt; ...

The content is styled to fill the content area with opaque background: 

  #main {background: #ffffff; Left: 0; Status: Completed; Top: 0; }

Is it a good idea to write code like this? It is more flexible than toxicon, but still allows to use quite structured formats, such as the DocBook, the advantage of this is that the source file is not only included documentation, but Naming or adding a source file to a file name ending in the documentation .htm is enough to be read by a web browser as HTML.

The only problem is that in the beginning, the + C comment XML document, which should (prevent me from correct if I am wrong)

edit : & lt ;! has been changed to use & lt ;! -... ---- & gt; To avoid conflict with to - .

Combining languages ​​(in this case C ++ and HTML) is never a good thing, and Should be done at least whenever possible. It annoys the actual code and makes it less readable (many, in fact). As long as it is not possible by the policies of the company, I ask all questions on the use of inline documents. The code can be read and understood easily, standing on your side. As a developer, I do not want to use the code's parallel help file; It's just tedious.

There are exceptions, of course, as in when you are developing a closed source library, the libraries can not read the user code, so they need an option. I will use something like Doxygen, but only for the public API, no internal code will be documented in such a way; There should be no need for this, otherwise it should be refined.

I never mix raw HTML and code. It's just very ugly if you think that raw HTML will be easy in case of your use, then I recommend placing it in a parallel file of source code, e.g., Fu. CPP and FU In this way, this code will not interfere in reading, and it will still be easy to maintain.


Comments

Post a Comment

Popular posts from this blog

c# - sqlDecimal to decimal clr stored procedure Unable to cast object of type 'System.Data.SqlTypes.SqlDecimal' to type 'System.IConvertible' -

-
I'm new to this I'm writing a clr. stored procedure that can be used to get values ​​used in a calculation Call for another stored procedure for Gives an archived methodology int (I think SqlInt32? Value of the table's value is int) which is then necessary to convert to decimal. Here I have the code: Public static integral mood (SQL MDMMYLUE, escalistering AMY type, out of SQLDCM Result) {aResult = 0; Try {SqlConnection conn = New SqlConnection ("Reference Connection = True"); SqlCommand cmd = New SqlCommand ("sp_GetType", conn); Cmd.Parameters.AddWithValue ("@ myValueType", aMyValueType); Cmd.CommandType = CommandType.StoredProcedure; Conn.Open (); Object type = CMD. Exclamation Asser (); Conn.Close (); Decimal type FORCalculation = Convert. ToDecimal (type); Decimal value = convert toDecimal (aMyValue); // ** calculation calc = new calculation (); Decimal result = calorie.docalulation (typefarculation, value); I get an exception...
Read more

Calling GetGUIThreadInfo from Outlook VBA -

-
I need to find the active window'm writing a VBA macro in MS Outlook, which is a specific process. The goal of this is to get the active window / document name even if its original application has more than one document interface. User processor with GetCurrentThreadId is active, I am using GetGUIThreadInfo to get .dll. Here is the correct code: private type RECT as as Left LongPtr top LongPtr right LongPtr down LongPtr termination of private type GUITHREADINFO cbSize as LongPtr flags LongPtr hwndActive LongPtr hwndFocus LongPtr hwndCapture LongPtr as as as as as reset as LongPtr rcCaret as LongPtr hwndCreate as LongPtr hwndMoveSize as HwndMenuOwner end of Private Equity PtrSafe function GetWindowThreadProcessId Lib "user32" (_BVV hnw LongPtr as LongPtr Nig Mr. announced as PtrSafe function GetGUIThreadInfo Lib "user32" _ (ByVal dwthreadid as LongPtr, _ lpguithreadinfo as GUITHREADINFO) LongPtr Sub MyFunction () as dim strWindowTitle string = space as s...
Read more

Obfuscating Python code? -

-
I'm looking for a way to hide my Python source code. print "Hello World!" How can I encode this example so that it is not human-readable? I have been asked to use Base 64 but I'm not sure how. itemprop = "text"> It is limited only, first level ambiguous resolution, but has built-in: byte-code in Python Is a compiler for: dragon-o-m py_compile & lt; Your program.py & gt; creates a .pyo file with a byte-code, and where the docstrings are removed, etc. You can rename .pyo with the .py extension, and python & lt; Your program.py & gt; runs as your program, but it does not have your source code. PS : If your program blur modules like this, you need to rename them with the .pyc suffix (I Not sure it will not break a day), or you can work with .pyo and run them with python -o ... .pyo ( Import should work). This will allow dragon to search your modules (otherwise, Python looks for the .py module).
Read more