diff --git a/.gitignore b/.gitignore index 8dc20a1..300935c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,7 +1,4 @@ *.pyc -eclcc.log -*.py~ -.project # OS generated files # ###################### @@ -12,5 +9,9 @@ eclcc.log .Trashes ehthumbs.db Thumbs.db - - +.vscode +build/* +ecldoc.egg-info +ecldoc-**.tar.gz +dist/ +textput.log \ No newline at end of file diff --git a/CodingPractices.rst b/CodingPractices.rst new file mode 100644 index 0000000..6a7a9ea --- /dev/null +++ b/CodingPractices.rst @@ -0,0 +1,140 @@ +============================ +Recommended Coding Practices +============================ + +This document recommends certain practices for developing code documentation +so that ECLdoc can rendered it as a professional looking document, and so that +the resulting documentation is largely consistent from project to project. + +Use of HTML tags: + +ECLdoc ignores the line formatting of documentation strings and treats end-of-line +as a space. Comments that are formatted as multiple lines with bullet-lists or +other structure will be rendered as a run-on paragraph, and may be difficult to +follow without adding additional markup to improve readability. + +For example, the following comment section: + +/** + * This is the warp drive implementation module + * It serves three purposes: + * - The first purpose + * - The second purpose + * - The third purpose + **/ + +This would be rendered by ECLdoc as: + +This is the warp drive implementation module It serves three purposes: - The +first purpose - The second purpose - The third purpose + +ECLdoc supports certain html formatting tags that allow this to be fixed: + - allow creation of lists and list items + -
, 
(i.e. preformatted) retain the structure and enclose + the structure in a gray bounding box + -

(i.e. new paragraph) causes the following text to be started on + a new line. + - , (i.e. bold) + +The list tags (