Well here is the first cut of the comment parser. Amazing how many little things you find to fix as soon as you think you are ready to share :) https://github.com/ethanpost/GO I am going to add a bunch of other stuff to the package (some string functions already added) over time but the doc_to_markdown procedure is the focus for now. The go_doc.pdf file was created by getting parsing the docs using doc_to_markdown procedure and then uploading to stackedit.io. Plenty of bugs and not totally PLDOC compatible but a start but it is working for me. Thanks, EP On Thu, Jan 15, 2015 at 2:39 PM, Ethan Post <post.ethan@xxxxxxxxx> wrote: > I am throwing together a PL/SQL comment parser and will share it when I am > done. Not going to put too much into this and don't want to over think it > but wanted to share here and if you have any suggestions let me know and > maybe I can incorporate them. > > I have looked at PLDOC and it isn't quite what I need. > > I am trying to adhere to the PLDOC/JAVADOC format to some degree in case I > end up wanting to use that in the future. > > This is going to be a procedure which parses USER_SOURCE and puts the > comments in a table (better than a separate java program IMO). Once that is > all working I will write a parser which puts it all in Markdown I think. > For now my goal is to get the parsing procedure built and get the data into > a table. The final outputs will come later. Ideally everything will live in > the database and the outputs can be viewed using a SELECT statement. > > Some of the tags below require a bit more explanation. > > @user is meant for the end user of a product, in this case a PLSQL > framework which is written by me but occasionally used by many technical > staff. These folks need docs but not dev type docs. I have found it > impossible to maintain any type of docs outside the product for a number of > reasons. Keeping all docs inline with code is maintainable and will keep > the managers off my back when they ask for docs who are looking more for > information on capabilities and features, which for this code base will > still work to keep with the PLSQL. > > @feature is meant to express a feature of the program. For example > moon_phase procedure might be a good place to store the comment "We monitor > all phases of the moon.". This can be handed off to the sales dept to help > promote the benefits of the program and you get an easy way to maintain > this list. > > Here is the format I am current working on parsing. > > function is_sql_hot (p_foo_var number) returns number is > begin > /* Short bit of text about what the procedure or function does. > > Detailed text here is optional and you can use any format here you want > and > it can go on and on > and on > > @parm P_FOO_VAR The number of times you added more commits to your > code to prevent snapshot too old errors. > @return Returns 0 if you admit we have all done it at least > once and 1 if you are lying. > @throws Error handlers? I don't need no stinkin error > handler. > @user Hot SQL is saved in the HOT_SQL_REPO table which is > better than TMI_SQL_HIST. > @fyi Do you know how to find the latest about hot sql? > @feature Our program frequently monitors the Hottest SQL! > @todo Figure out what Hot SQL means. > @tag Performance Monitoring, SQL > */ > null; > end; > / > > Thanks, > Ethan >